From 8fbd45c24e9ffd83a93c073401d98568883e05fa Mon Sep 17 00:00:00 2001
From: Tristan Cacqueray <tdecacqu@redhat.com>
Date: Sat, 6 Jan 2024 11:12:28 -0500
Subject: [PATCH 1/4] doc: replace Makefile with Justfile

---
 CONTRIBUTING.md          |  2 +-
 Justfile                 | 68 ++++++++++++++++++++++++++++++++++++++++
 Makefile                 | 38 ----------------------
 doc/tutorial/protobuf.md |  2 +-
 nix/default.nix          |  9 ++++++
 5 files changed, 79 insertions(+), 40 deletions(-)
 create mode 100644 Justfile

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 31f6be65b..c11f79cb2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -214,7 +214,7 @@ protobuf definitions present in the [./schemas/monocle folder](./schemas/monocle
 the api and web client by running the protoc command using the Makefile:
 
 ```ShellSession
-$ make codegen
+$ just codegen
 ```
 
 ## Create a monocle build
diff --git a/Justfile b/Justfile
new file mode 100644
index 000000000..44a1ac5b9
--- /dev/null
+++ b/Justfile
@@ -0,0 +1,68 @@
+# Copyright (C) 2023 Monocle authors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# doc: https://just.systems/man/en/chapter_1.html
+
+PINCLUDE := "-I /usr/include ${PROTOC_FLAGS} -I ./schemas/"
+# just doesn't support array so we create a space separated string for bash
+# see: https://github.com/casey/just/issues/1570
+PBS := `ls schemas/monocle/protob/*.proto | grep -v http.proto | sed 's/schemas.//' | tr '\n' ' '`
+
+# Update code after changing protobuf schema (./schemas/monocle/protob), ci.dhall or architecture.plantuml
+codegen: codegen-ci codegen-doc codegen-stubs codegen-javascript codegen-openapi codegen-haskell
+
+# Generate CI config from .github/workflows/ci.dhall
+[private]
+codegen-ci:
+    set -euxo pipefail
+    echo "(./.github/workflows/ci.dhall).Nix" | dhall-to-yaml > .github/workflows/nix.yaml
+    echo "(./.github/workflows/ci.dhall).NixBuild" | dhall-to-yaml > .github/workflows/nix-build.yaml
+    echo "(./.github/workflows/ci.dhall).Web" | dhall-to-yaml > .github/workflows/web.yaml
+    echo "(./.github/workflows/ci.dhall).Docker" | dhall-to-yaml > .github/workflows/docker.yaml
+    echo "(./.github/workflows/ci.dhall).Publish-Master-Image" | dhall-to-yaml > .github/workflows/publish-master.yaml
+    echo "(./.github/workflows/ci.dhall).Publish-Tag-Image" | dhall-to-yaml > .github/workflows/publish-tag.yaml
+
+# Generate doc/architecture.png from doc/architecture.plantuml
+# just doesn't support timestamp based rule, so we keep make for plantuml
+# see: https://github.com/casey/just/issues/867
+[private]
+codegen-doc:
+    set -euxo pipefail
+    make doc/architecture.png
+
+# Generate HTTP clients and server
+[private]
+codegen-stubs:
+    set -euxo pipefail
+    mkdir -p srcgen/
+    cabal -fcodegen run monocle-codegen ./schemas/monocle/protob/http.proto ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs ./srcgen/WebApi.res
+    fourmolu -i ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs
+    ./web/node_modules/.bin/bsc -format ./srcgen/WebApi.res > ./web/src/components/WebApi.res
+    rm -Rf srcgen/
+
+# Generate haskell data type from protobuf
+[private]
+codegen-haskell:
+    set -euxo pipefail
+    for pb in {{PBS}}; do \
+      compile-proto-file --includeDir /usr/include --includeDir schemas/ --includeDir ${PROTOBUF_SRC} --proto ${pb} --out codegen/; \
+    done
+    find codegen/Monocle -type f -name "*.hs" -exec sed -i {} -e '1i{-# LANGUAGE NoGeneralisedNewtypeDeriving #-}' \;
+    fourmolu -i codegen/Monocle
+
+# Generate javascript data type from protobuf
+[private]
+codegen-javascript:
+    set -euxo pipefail
+    rm -f web/src/messages/*
+    for pb in {{PBS}}; do \
+      ocaml-protoc {{PINCLUDE}} -bs -ml_out web/src/messages/ schemas/${pb}; \
+    done
+    python3 ./codegen/rename_bs_module.py ./web/src/messages/
+
+# Generate openapi from protobuf
+[private]
+codegen-openapi:
+    set -euxo pipefail
+    protoc {{PINCLUDE}} --openapi_out=./doc/ monocle/protob/http.proto
+    echo Created doc/openapi.yaml
diff --git a/Makefile b/Makefile
index 27cec1b46..4715e2647 100644
--- a/Makefile
+++ b/Makefile
@@ -1,43 +1,5 @@
 # Copyright (C) 2021 Monocle authors
 # SPDX-License-Identifier: AGPL-3.0-or-later
-.PHONY: up-stage
-
-
-BASEDIR = monocle/protob
-MESSAGES = $(BASEDIR)/search.proto $(BASEDIR)/config.proto $(BASEDIR)/login.proto $(BASEDIR)/metric.proto $(BASEDIR)/auth.proto
-CRAWLER = $(BASEDIR)/change.proto $(BASEDIR)/issue.proto $(BASEDIR)/crawler.proto
-PINCLUDE = -I /usr/include $(PROTOC_FLAGS) -I ./schemas/
-
-codegen: codegen-ci codegen-javascript codegen-stubs codegen-openapi codegen-haskell doc/architecture.png
-
-codegen-ci:
-	echo "(./.github/workflows/ci.dhall).Nix" | dhall-to-yaml > .github/workflows/nix.yaml
-	echo "(./.github/workflows/ci.dhall).NixBuild" | dhall-to-yaml > .github/workflows/nix-build.yaml
-	echo "(./.github/workflows/ci.dhall).Web" | dhall-to-yaml > .github/workflows/web.yaml
-	echo "(./.github/workflows/ci.dhall).Docker" | dhall-to-yaml > .github/workflows/docker.yaml
-	echo "(./.github/workflows/ci.dhall).Publish-Master-Image" | dhall-to-yaml > .github/workflows/publish-master.yaml
-	echo "(./.github/workflows/ci.dhall).Publish-Tag-Image" | dhall-to-yaml > .github/workflows/publish-tag.yaml
 
 doc/architecture.png: doc/architecture.plantuml
 	plantuml ./doc/architecture.plantuml
-
-codegen-stubs:
-	mkdir -p srcgen/
-	(cabal -fcodegen run monocle-codegen ./schemas/$(BASEDIR)/http.proto ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs ./srcgen/WebApi.res)
-	fourmolu -i ./src/Monocle/Client/Api.hs ./src/Monocle/Servant/HTTP.hs
-	./web/node_modules/.bin/bsc -format ./srcgen/WebApi.res > ./web/src/components/WebApi.res
-	rm -Rf srcgen/
-
-codegen-haskell:
-	sh -c 'for pb in $(MESSAGES) $(CRAWLER); do compile-proto-file --includeDir /usr/include --includeDir schemas/ --includeDir ${PROTOBUF_SRC} --proto $${pb} --out codegen/; done'
-	find codegen/Monocle -type f -name "*.hs" -exec sed -i {} -e '1i{-# LANGUAGE NoGeneralisedNewtypeDeriving #-}' \;
-	fourmolu -i codegen/Monocle
-
-codegen-javascript:
-	rm -f web/src/messages/*
-	sh -c 'for pb in $(MESSAGES) $(CRAWLER); do ocaml-protoc $(PINCLUDE) -bs -ml_out web/src/messages/ schemas/$${pb}; done'
-	python3 ./codegen/rename_bs_module.py ./web/src/messages/
-
-codegen-openapi:
-	protoc $(PINCLUDE) --openapi_out=./doc/ $(BASEDIR)/http.proto
-	@echo Created doc/openapi.yaml
diff --git a/doc/tutorial/protobuf.md b/doc/tutorial/protobuf.md
index 3a8e16fe9..2707dab4b 100644
--- a/doc/tutorial/protobuf.md
+++ b/doc/tutorial/protobuf.md
@@ -161,5 +161,5 @@ We would like to avoid doing the above manually, thus Monocle provide a codegen
 to automate this process in three steps:
 
 - 1. Write protobuf definitions in the `schemas/` folder, (and add newly created files to the Makefile `MESSAGES` list)
-- 2. Generate the code by running `make codegen-with-container`
+- 2. Generate the code by running `just codegen`
 - 3. Implement the API, e.g. open the `web/src/components/WebApi.res` module to use it.
diff --git a/nix/default.nix b/nix/default.nix
index ce7bdc0a8..04cd048ca 100644
--- a/nix/default.nix
+++ b/nix/default.nix
@@ -48,6 +48,14 @@ let
     ];
   };
 
+  # pull latest nixpkgs for just [private] support
+  latestPkgs = import (pkgs.fetchFromGitHub {
+    owner = "NixOS";
+    repo = "nixpkgs";
+    rev = "32ea06b23546a0172ac4e2aa733392e02f57503e";
+    sha256 = "sha256-NuRRuBO3ijXIu8sD9WaW5m6PHb3COI57UtHDMY+aGTI=";
+  }) { system = "x86_64-linux"; };
+
   # create the main package set without options
   pkgs = nixpkgsSrc { system = "x86_64-linux"; };
   pkgsNonFree = nixpkgsSrc {
@@ -549,6 +557,7 @@ in rec {
     packages = p: [ (addExtraDeps p.monocle) p.pretty-simple ];
 
     buildInputs = [
+      latestPkgs.just
       hspkgs.hlint
       hspkgs.apply-refact
       hspkgs.ghcid

From d9788178006d0ffc7dbdfed475233c1d9744bc60 Mon Sep 17 00:00:00 2001
From: Tristan Cacqueray <tdecacqu@redhat.com>
Date: Sat, 6 Jan 2024 11:39:14 -0500
Subject: [PATCH 2/4] doc: move common commands to the just file

---
 CONTRIBUTING.md                    | 50 ++++++++++++++-------------
 Justfile                           | 54 ++++++++++++++++++++++++++++++
 nix/default.nix                    |  7 ----
 src/Monocle/Backend/Provisioner.hs |  2 +-
 4 files changed, 82 insertions(+), 31 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c11f79cb2..2ef698fda 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ This section describes how to start the Monocle services directly on your host.
 #### Start ElasticSearch
 
 ```ShellSession
-nix develop --command elasticsearch-start
+just elastic
 ```
 
 #### Start the Monocle API
@@ -41,13 +41,13 @@ nix develop --command elasticsearch-start
 The API serves the web UI and the Monocle API. The web App must be built first by running:
 
 ```ShellSession
-cd web && npm install && npm run build && cd -
+just build-web
 ```
 
 Then, ensure you have set the Monocle config file `config.yaml` (see [README.md](README.md#configuration)) and run:
 
 ```ShellSession
-nix develop --command monocle-repl
+just repl
 λ> import Monocle.Main
 λ> run $ defaultApiConfig 8080 "http://localhost:19200" "etc/config.yaml"
 ```
@@ -55,9 +55,12 @@ nix develop --command monocle-repl
 … or by running the executable:
 
 ```ShellSession
-CRAWLERS_API_KEY=secret MONOCLE_CONFIG=./etc/config.yaml nix develop --command cabal run -O0 monocle -- api
+just api
 ```
 
+> Make sure to setup your .env file, e.g. with:
+> (echo CRAWLERS_API_KEY=secret; echo MONOCLE_CONFIG=./etc/config.yaml) > .env
+
 The Monocle UI should be accessible:
 
 ```ShellSession
@@ -67,11 +70,14 @@ firefox http://localhost:8080
 #### Start the Monocle crawler process
 
 ```ShellSession
-nix develop --command monocle-repl
-λ> import Macroscope.Worker
-λ> import Macroscope.Main
-λ> import Monocle.Client (withClient)
-λ> withClient "http://localhost:8080" Nothing $ \client -> runMacroscope 19001 "etc/config.yaml" client
+just repl
+λ> Monocle.Client.withClient "http://localhost:8080" Nothing $ \client -> Macroscope.Main.runMacroscope 19001 "etc/config.yaml" client
+```
+
+… or by running the executable:
+
+```ShellSession
+just crawler
 ```
 
 ### Start the CLI
@@ -113,9 +119,8 @@ You might need to install the right Haskell plugin for your editor.
 ghcid automatically re-compiles the code when a haskell file change and display compilation
 errors and warnings.
 
-
 ```ShellSession
-nix develop --command monocle-ghcid
+just ghcid
 ```
 
 ### Run hoogle
@@ -123,7 +128,7 @@ nix develop --command monocle-ghcid
 Hoogle generates the documentation from the Monocle source code.
 
 ```ShellSession
-nix develop --command hoogle server -p 8081 --local --haskell
+just hoogle
 ```
 
 You can access the generated documentation on port 8081.
@@ -136,25 +141,25 @@ Ensure the service is started by running: `nix develop --command elasticsearch-s
 Run linters (fourmolu and hlint) with:
 
 ```ShellSession
-nix develop --command monocle-fast-ci-run
+just ci-fast
 ```
 
 When the linters fail, you can fix the issue automatically with:
 
 ```ShellSession
-nix develop --command monocle-reformat-run
+just fmt
 ```
 
 Run the full test suite with:
 
 ```ShellSession
-nix develop --command monocle-ci-run
+just ci
 ```
 
-Run a single test:
+Run a single test (on failure, tasty provides a pattern to re-run a single test):
 
 ```ShellSession
-cabal test --test-options='-p "Change stream"'
+just test "PATTERN"
 ```
 
 ## Start the web development server
@@ -162,7 +167,7 @@ cabal test --test-options='-p "Change stream"'
 Start the web dev server (hot-reload):
 
 ```ShellSession
-nix develop --command monocle-web-start
+just web
 firefox http://localhost:13000
 ```
 
@@ -188,7 +193,7 @@ ghcid --set ":set args api" --test 'CLI.main'
 Start Kibana with:
 
 ```ShellSession
-nix develop --command kibana-start
+just kibana
 ```
 
 Then access http://localhost:5601
@@ -198,9 +203,8 @@ Then access http://localhost:5601
 Provisonning fake data (only fake changes are supported) can be done using the repl:
 
 ```
-nix develop --command monocle-repl
-λ> import Monocle.Backend.Provisioner
-λ> runProvisioner "etc/config.yaml" "http://localhost:19200" "demo-fake-data" 300
+just repl
+λ> Monocle.Backend.Provisioner.runProvisioner "etc/config.yaml" "http://localhost:19200" "demo-fake-data" 300
 ```
 
 Prior to run the provisonner, add the *demo-fake-data* workspace in the config file with an
@@ -214,7 +218,7 @@ protobuf definitions present in the [./schemas/monocle folder](./schemas/monocle
 the api and web client by running the protoc command using the Makefile:
 
 ```ShellSession
-$ just codegen
+just codegen
 ```
 
 ## Create a monocle build
diff --git a/Justfile b/Justfile
index 44a1ac5b9..a8a1df2aa 100644
--- a/Justfile
+++ b/Justfile
@@ -3,11 +3,65 @@
 #
 # doc: https://just.systems/man/en/chapter_1.html
 
+# Load .env file
+set dotenv-load
+
 PINCLUDE := "-I /usr/include ${PROTOC_FLAGS} -I ./schemas/"
 # just doesn't support array so we create a space separated string for bash
 # see: https://github.com/casey/just/issues/1570
 PBS := `ls schemas/monocle/protob/*.proto | grep -v http.proto | sed 's/schemas.//' | tr '\n' ' '`
 
+# Start elasticsearch
+elastic:
+    nix develop --command elasticsearch-start
+
+# Start kibana
+kibana:
+    nix develop --command kibana-start
+
+# Start web devel server
+web:
+    nix develop --command monocle-web-start
+
+# Build the web interface
+build-web:
+    cd web && npm install && npm run build
+
+# Reformat and apply hlint hints
+fmt:
+    nix develop --command monocle-reformat-run
+
+# Run the full ci test suite
+ci:
+    nix develop --command monocle-ci-run
+
+# Run unit tests
+ci-fast:
+    nix develop --command monocle-fast-ci-run
+
+test pattern:
+    nix develop --command cabal -O0 test --test-options='-p "{{pattern}}"'
+
+# Start ghcid
+ghcid:
+    nix develop --command ghcid
+
+# Start hoogle to search documentation
+hoogle:
+    nix develop --command hoogle server -p 8081 --local --haskell
+
+# Start a ghci repl
+repl:
+    nix develop --command monocle-repl
+
+# Run the API
+api:
+    nix develop --command cabal run -O0 monocle -- api
+
+# Run the CRAWLER
+crawler:
+    nix develop --command cabal run -O0 monocle -- crawler
+
 # Update code after changing protobuf schema (./schemas/monocle/protob), ci.dhall or architecture.plantuml
 codegen: codegen-ci codegen-doc codegen-stubs codegen-javascript codegen-openapi codegen-haskell
 
diff --git a/nix/default.nix b/nix/default.nix
index 04cd048ca..85d4ec99a 100644
--- a/nix/default.nix
+++ b/nix/default.nix
@@ -336,12 +336,6 @@ in rec {
     cabal repl --build-depends pretty-simple monocle
   '';
 
-  monocleGhcid = pkgs.writeScriptBin "monocle-ghcid" ''
-    #!/bin/sh
-    set -x
-    ${hspkgs.ghcid}/bin/ghcid -c "cabal repl monocle" $*
-  '';
-
   monocleWebStart = pkgs.writeScriptBin "monocle-web-start" ''
     #!/bin/sh
     set -ex
@@ -366,7 +360,6 @@ in rec {
     elasticsearchStart
     monocleReplStart
     monocleWebStart
-    monocleGhcid
   ];
 
   # define the base requirements
diff --git a/src/Monocle/Backend/Provisioner.hs b/src/Monocle/Backend/Provisioner.hs
index c985d39db..96ceaecc9 100644
--- a/src/Monocle/Backend/Provisioner.hs
+++ b/src/Monocle/Backend/Provisioner.hs
@@ -57,7 +57,7 @@ runProvisioner configPath elasticUrl tenantName docCount = do
         case r of
           Left err -> logInfo "Unable to perform the provisionning" ["error" .= err]
           Right _ -> pure ()
-      Nothing -> pure ()
+      Nothing -> logWarn "Could not find tenant" []
 
 -- | Ensure changes have a unique ID
 setChangeID :: [EChange] -> IO [EChange]

From cea5db359a93b78d697151149e5884a04d139ac0 Mon Sep 17 00:00:00 2001
From: Tristan Cacqueray <tdecacqu@redhat.com>
Date: Sat, 6 Jan 2024 12:13:54 -0500
Subject: [PATCH 3/4] doc: fix hoogle service

---
 CONTRIBUTING.md |  4 +++-
 Justfile        |  6 +++++-
 flake.nix       |  2 ++
 nix/default.nix | 12 ++++++++++++
 4 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2ef698fda..9708c39d8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -128,9 +128,11 @@ just ghcid
 Hoogle generates the documentation from the Monocle source code.
 
 ```ShellSession
-just hoogle
+just hoogle-monocle
 ```
 
+> To avoid building monocle, you can start hoogle with only the dependencies using `just hoogle`
+
 You can access the generated documentation on port 8081.
 
 ## Running tests
diff --git a/Justfile b/Justfile
index a8a1df2aa..52a17c807 100644
--- a/Justfile
+++ b/Justfile
@@ -46,9 +46,13 @@ test pattern:
 ghcid:
     nix develop --command ghcid
 
+# Start hoogle with local monocle documentation
+hoogle-monocle:
+    nix develop .#hoogle-monocle --command hoogle server -p 8081 --local --haskell
+
 # Start hoogle to search documentation
 hoogle:
-    nix develop --command hoogle server -p 8081 --local --haskell
+    nix develop .#hoogle --command hoogle server -p 8081 --local --haskell
 
 # Start a ghci repl
 repl:
diff --git a/flake.nix b/flake.nix
index ea36dbbe3..0ee122df1 100644
--- a/flake.nix
+++ b/flake.nix
@@ -38,6 +38,8 @@
     in {
       haskellExtend = legacy.hExtend;
       devShell."x86_64-linux" = legacy.shell;
+      devShells."x86_64-linux".hoogle-monocle = legacy.hoogle-monocle;
+      devShells."x86_64-linux".hoogle = legacy.hoogle;
       devShells."x86_64-linux".ci = legacy.ci-shell;
       devShells."x86_64-linux".monitoring = legacy.monitoring-shell;
       packages."x86_64-linux".default = legacy.monocle-exe;
diff --git a/nix/default.nix b/nix/default.nix
index 85d4ec99a..bf419e40a 100644
--- a/nix/default.nix
+++ b/nix/default.nix
@@ -546,6 +546,18 @@ in rec {
     name = "monocle-services";
     buildInputs = base-req ++ services-req;
   };
+
+  # load hoogle with the current version of monocle
+  hoogle-monocle = pkgs.mkShell {
+    buildInputs = [ (hsPkgs.ghcWithHoogle (p: [ p.monocle ])) ];
+  };
+
+  # load hoogle with monocle dependencies only
+  hoogle = hsPkgs.shellFor {
+    packages = p: [ p.monocle ];
+    withHoogle = true;
+  };
+
   shell = hsPkgs.shellFor {
     packages = p: [ (addExtraDeps p.monocle) p.pretty-simple ];
 

From b9624a54ab1e8466cc77767a0abcee89b210a356 Mon Sep 17 00:00:00 2001
From: Tristan Cacqueray <tdecacqu@redhat.com>
Date: Sat, 6 Jan 2024 12:38:48 -0500
Subject: [PATCH 4/4] doc: add haddock command

---
 CONTRIBUTING.md | 8 ++++++++
 Justfile        | 4 ++++
 2 files changed, 12 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9708c39d8..2190396a8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -94,6 +94,14 @@ For instance running a crawler:
 nix run . -- lentille github-projects --url https://api.github.com/graphql --token <a-valid-token> --organization change-metrics
 ```
 
+### Build the documentation
+
+Build and read the code documentation:
+
+```
+just docs
+```
+
 ## nix-develop
 
 The nix develop shell provides development tooling such as:
diff --git a/Justfile b/Justfile
index 52a17c807..a773eee70 100644
--- a/Justfile
+++ b/Justfile
@@ -46,6 +46,10 @@ test pattern:
 ghcid:
     nix develop --command ghcid
 
+# Build and open the documentation
+docs:
+    nix develop --command cabal haddock --open
+
 # Start hoogle with local monocle documentation
 hoogle-monocle:
     nix develop .#hoogle-monocle --command hoogle server -p 8081 --local --haskell