image:https://img.shields.io/clojars/v/io.github.pfeodrippe/pitoco.svg[link="http://clojars.org/io.github.pfeodrippe/pitoco",title="Clojars Project"]

== Pitoco

Create Malli (API) schemas from captured HTTP requests and responses or from recording inputs and outputs of instrumented functions, e.g. during a test run. You can also diff the API schemas (for example to explore how the REST API changed between versions) and the instrumentation-based process includes the schemas in the functions' docstrings, which might help in familiarizing with an unknown code base.

We use https://github.com/stathissideris/spec-provider to infer Malli (https://github.com/metosin/malli) schemas and https://github.com/wilkerlucio/pathom3 as our main API.

Malli has a way to generate schemas, but it was https://github.com/metosin/malli/issues/191[too slow] in comparison with spec-provider.

See a post about Pitoco at https://pfeodrippe.github.io/posts/pitoco.html.

== Installation

Use it directly from github for now (lein and deps should be able to do it).

== Usage

See the test file and rich comments (comment) in the link:src/pitoco/core.clj[core] for usage.

We have a web app which uses Pitoco so you can visualize your schemas easily, but you can use Pitoco as a library.

You can start the server at http://localhost:8081 by loading the pitoco.server namespace. Now start the shadow-cljs server and access http://localhost:8000.

=== Generating API schemas from captured HTTP requests and responses

The first use case of Pitoco is generating Malli schemas for REST APIs based on captured HTTP requests and responses (using either https://en.wikipedia.org/wiki/HAR_(file_format)[HAR] archives from your browser or .pcap files from tcpdump).

See a quick video at https://youtu.be/iMcUTygFrfk.

=== Generating function schemas from recorded inputs and outputs of instrumented vars

The second use case of Pitoco is to instrument selected vars, record their inputs and outputs, and generate Malli schemas from those, including them in the vars' docstrings.

See the pitoco.instrumentation namespace.

Also you can watch https://youtu.be/MloJSCl38d0.

There is a VSCode Extension where you can visualize the inferred schemas (+ examples) using VSCode in the web (e.g. during PRs so you can have augmented context when needed).

== Inspirations

• https://www.akitasoftware.com/blog

== Developer setup

Clone the repo and enter in the repo

[source,shell]

git clone https://github.com/pfeodrippe/pitoco cd pitoco

Enter in the web_app directory, install npm deps and start the frontend.

[source,shell]

cd web_dev npm install npm start

The npm start command should spawn both shadow-cljs and tailwindcss.

Then in another terminal, you can enter in the web_dev folder again and start the backend.

[source,shell]

cd pitoco/web_dev clj -e "(require,'pitoco.server)"

After a while, the frontend will be available at http://localhost:8000[localhost:8000]. You can connect on it via browser.

The backend will be available at http://localhost:8081[localhost:8081]. You can check if it is running with curl

[source,shell]

curl http://localhost:8081/chsk

{"type":"exception","class":"clojure.lang.ExceptionInfo"}