Review clojure tools use and general use invokations

[lread]

Context

I'm working on cljdoc/cljdoc-check-action#4.

Currently

We have 3 invocation paths for cljdoc-analyzer

1. invoked by cljdoc itself via cljdoc-analyzer.cljdoc-main - never resolves lib
2. invoked for general use via cljdoc-analyzer.main - always resolves lib
3. invoked for general use as Clojure tool via cljdoc-analyzer.deps-tools
   1. analyze command - when requested, resolves lib
   2. analyze-local command - never resolves lib

The GitHub cljdoc check action uses the 3rd variant.

The differences between all of the above are confusing and hard to remember/maintain/explain.

Cljdoc usage...

Specifies all of: project version pompath and jarpath.

Both project and version are treated as trusted descriptors and not used to resolve the lib.

Why are project and version specified when they could be read from pom?
Maybe because cljdoc knows project and version and just passes them on?
Maybe for certain local test uses (cljdoc ingest maybe?), it needs to override these values?

Clojure Tools Invocation

When invoked as a Clojure tool, we have two commands: analyze and analyze-local.
But maybe we don't need the distinction?

1. If project and version are specified (and jarpath and pompath are not) resolve the dep and automatically populate: jarpath, pompath.
2. Otherwise
   1. If jarpath is not specified, search under ./target for a single matching candidate.
   2. If pompath is not specified, try to find a suitable pom in jar
      1. if project is specified use it to disambiguate find pom in jar META-INF/maven/$project /pom.xml.
      2. Otherwise match single pom.xml in jar and discover from pom: project, version
3. extra-repos and output-filename supported regardless.

Ah. I see analyze command has a :download arg. It will only resolve the lib if this arg is specified. But if jarpath is not specified wouldn't you always need to resolve?

Note that jarpath and pompath can be local files or URLs.
Pompath is slurped and jarpath is downloaded if necessary.

I'll have to sleep on this.

Consolidation of convenience usages

When invoked for convenience, we have two separate entry point namespaces.

1. cljdoc-analyzer.main
2. cljdoc-analyzer.deps-tools

The first entry point takes some care to validate arguments via cli-matic.
The second does not validate args.

The first analyze command seems to sorta replicate analyze for 2nd, but the 2nd hardcodes exclude-with.
The first does not replicate analyze-local for the 2nd.

Consolidating both usages would help to ensure they stay in sync and that args are validated in the same way.
For example, I see languages did not get added deps tools usage.

Docs

I'll validate/update docs for as part of resolving this issue.

Cljdoc vs convenience usages

So... folks will typically use convenience invocations of cljdoc to diagnose issues with cljdoc analysis. The Clojure tools invocation is used by the GitHub check action. If convenience usages behaviour drifts too far from cljdoc usage, we are likely doing folks a disservice.