pkgs/companion: attempt to understand & update

this whole thing is horrible.

The previous state failed to build since some package on yarn got
yanked. This state fails to build with some javascript exception in yarn
that has me stumped.

It might help to try other commits of the companion, dunno

Also added some comments. Half of this thing I have no idea what it
does, but perhaps my notes on the other half can help someone else with
fixing it 🤷‍

pkgs/companion/default.nix

@@ -1,24 +1,64 @@
-{ stdenv, mkYarnPackage, mkYarnModules, fetchFromGitHub, libsass, python, python3, pkg-config, libusb, fetchurl, nodejs, electron, writeText, makeWrapper, udev, nodePackages, libvips }:
+{ stdenv
+, mkYarnPackage
+, mkYarnModules
+, fetchFromGitHub
+, libsass
+, python
+, python3
+, pkg-config
+, libusb
+, fetchurl
+, nodejs
+, electron
+, writeText
+, makeWrapper
+, udev
+, nodePackages
+, libvips
+}:
+
+# some weird javascript thingy that runs our tally lights on conferences.
+#
+# in case it breaks or you want to update it:
+#  1. update companion sources below (also update the hash)
+#  2. re-generate the yarn.nix / yarn-webui.nix files (see comments below)
+#  3. try re-generating yarn.lock itself (`yarn install --mode update-lockfile`)
+#
+# if things break, try taking a look at yarn2nix's documentation. In
+# nix-typical fashion, it was deleted when yarn2nix got integrated into
+# nixpkgs; a shorter version is now in the nixpkgs manual:
+#   - https://nixos.org/manual/nixpkgs/stable/#javascript-tool-specific
+# sometimes the archived original documentation can still be helpful:
+#   - https://github.com/nix-community/yarn2nix
 
 let
   version = "2.1.3";
+
   source = fetchFromGitHub {
     owner = "bitfocus";
     repo = "companion";
-#   rev = "v${version}";
+    rev = "b653211f5507a090a120fa3e819ab3044405e461";
-    rev = "1cc51029a19d7263a09058f73922277ca53a1583";
+    sha256 = "0gvibbhfqa9gk8cf3m07gd5dbik3kbpr03hx2pppqnh9pfrx35qh";
-    sha256 = "0305wwdic3n20whzhh9zqcd3dwj7hc4fpycs645ncc3sk48azmj0";
   };
+
   nodeHeaders = fetchurl {
     url = "https://nodejs.org/download/release/v${nodejs.version}/node-v${nodejs.version}-headers.tar.gz";
     sha256 = "19b0dg8292cjx758wlrvpb3jf520bpyvjal2n7r4fyvk38x9flik";
   };
+
+  # the companion's web ui. In a seperate derivation, but is symlinked into
+  # the companion itself.
   webui = mkYarnPackage rec {
     inherit version;
     pname = "bitfocus-companion-webui";
 
     src = "${source}/webui";
 
+    # nixified dependencies generated using `yarn2nix`. Must be re-generated
+    # when updating the companion using yarn2nix on the yarn.lock file of the
+    # webui.
+    yarnNix = ./yarn-webui.nix;
+
     configurePhase = "
       cp -r $node_modules node_modules
       chmod -R u+w node_modules
@@ -27,7 +67,6 @@ let
     installPhase = "mv build $out";
     distPhase = "true";
 
-    yarnNix = ./yarn-webui.nix;
 
     pkgConfig = {
       node-sass = {
@@ -38,17 +77,38 @@ let
   };
 
   yarnModulesNoWorkspace = args: (mkYarnModules args).overrideAttrs(old: {
-    buildPhase = builtins.replaceStrings [" ./package.json"] [" /dev/null; cp deps/*/package.json ."] old.buildPhase;
+    # this replaces exactly one occurance of that string in
+    # <nixpkgs>/pkgs/development/tools/yarn2nix-moretea/yarn2nix/default.nix
+    buildPhase = builtins.replaceStrings
+      [" ./package.json"]
+      [" /dev/null; cp deps/*/package.json ."]
+      old.buildPhase;
   });
 
+in stdenv.mkDerivation rec {
+  inherit version;
+  pname = "bitfocus-companion";
+
+  src = source;
+
+  # yarn modules needed for the build; these would usually be fetched by yarn
+  # when running `yarn build`.
   modules = yarnModulesNoWorkspace rec {
     inherit version;
     pname = "companion-modules";
     name = "${pname}-${version}";
+
+    # A nixified version of yarn's yarn.lock file. If anything in here breaks,
+    # try regenerating it using `yarn2nix` (found in nixpkgs.yarn2nix) on the
+    # yarn.lock file found in the companion's source tree (also try a newer
+    # version while you're at it).
     yarnNix = ./yarn.nix;
+
+    # no idea what these two do tbh
     packageJSON = "${source}/package.json";
     yarnLock = "${source}/yarn.lock";
 
+    # ???
     pkgConfig = {
       node-hid = {
         buildInputs = [ udev libusb python3 pkg-config ];
@@ -66,11 +126,6 @@ let
       };
     };
   };
-in stdenv.mkDerivation rec {
-  inherit version webui modules;
-  pname = "bitfocus-companion";
-
-  src = source;
 
   nativeBuildInputs = [ makeWrapper ];