From 8eece32a8db35207dc6d4c2da61bdb3d2aa94f66 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Sat, 20 May 2023 14:57:51 +0200
Subject: [PATCH] REFACTOR: clean the root of the repo (#9231)

# Description
i've almost always wanted to clean up the root of the repo, so here is
my take at it, with some important advice given by @fdncred :relieved:

- `README.release.txt` is now gone and directly inline in the
`release-pkg` script used in the `release` *workflow*
- `build.rs` has been moved to `scripts/` and its path has been changed
in
[`Cargo.toml`](https://github.com/amtoine/nushell/blob/refactor/clean-root/Cargo.toml#L3)
according to the [*Build Scripts*
section](https://doc.rust-lang.org/cargo/reference/build-scripts.html#build-scripts)
of *The Cargo Book*
- i've merged `images/` into `assets/` and fix the only mention to the
GIF in the README
- i've moved the `docs/README.md` inside the main `README.md` as a new
[*Configuration*
section](https://github.com/amtoine/nushell/tree/refactor/clean-root#configuration)
- the very deprecated `pkg_mgrs/` has been removed
- all the `.nu`, `.sh`, `.ps1` and `.cmd` scripts have been moved to
`scripts/`

### things i've left as-is
- all the other `.md` documents
- the configuration files
- all the Rust and core stuff
- `docker/`
- `toolkit.nu`
- the `wix/` diretory which appears to be important for `winget`

# User-Facing Changes
scripts that used to rely on the paths to some of the scripts should now
call the scripts inside `scripts/` => i think this for the greater good,
it was not pretty nor scalable to have a bunch of scripts in the root of
our main `nushell` :scream:

*i even think we might want to move these scripts outside the main
`nushell` repo*
maybe to `nu_scripts` or some other tool :+1:

# Tests + Formatting
- :green_circle: `toolkit fmt`
- :green_circle: `toolkit clippy`
- :black_circle: `toolkit test`
- :black_circle: `toolkit test stdlib`

# After Submitting
```
$nothing
```
---
 .github/workflows/release-pkg.nu              |   4 +-
 Cargo.toml                                    |   1 +
 README.md                                     |  19 +++++-
 README.release.txt                            |   3 -
 {images => assets}/nushell-autocomplete6.gif  | Bin
 build-all.nu                                  |  25 --------
 coverage-local.nu                             |  54 ----------------
 docs/README.md                                |  15 -----
 pkg_mgrs/winget/0.17.yml                      |  16 -----
 scripts/README.md                             |  27 ++++++++
 .../build-all-maclin.sh                       |  16 ++++-
 .../build-all-windows.cmd                     |   0
 scripts/build-all.nu                          |  36 +++++++++++
 build.rs => scripts/build.rs                  |   0
 scripts/coverage-local.nu                     |  60 ++++++++++++++++++
 .../coverage-local.sh                         |  26 +++++---
 install-all.ps1 => scripts/install-all.ps1    |   0
 install-all.sh => scripts/install-all.sh      |   9 ++-
 .../register-plugins.nu                       |   0
 uninstall-all.sh => scripts/uninstall-all.sh  |   0
 20 files changed, 180 insertions(+), 131 deletions(-)
 delete mode 100644 README.release.txt
 rename {images => assets}/nushell-autocomplete6.gif (100%)
 delete mode 100644 build-all.nu
 delete mode 100755 coverage-local.nu
 delete mode 100644 docs/README.md
 delete mode 100644 pkg_mgrs/winget/0.17.yml
 create mode 100644 scripts/README.md
 rename build-all-maclin.sh => scripts/build-all-maclin.sh (71%)
 rename build-all-windows.cmd => scripts/build-all-windows.cmd (100%)
 create mode 100644 scripts/build-all.nu
 rename build.rs => scripts/build.rs (100%)
 create mode 100755 scripts/coverage-local.nu
 rename coverage-local.sh => scripts/coverage-local.sh (60%)
 rename install-all.ps1 => scripts/install-all.ps1 (100%)
 rename install-all.sh => scripts/install-all.sh (78%)
 rename register-plugins.nu => scripts/register-plugins.nu (100%)
 rename uninstall-all.sh => scripts/uninstall-all.sh (100%)

diff --git a/.github/workflows/release-pkg.nu b/.github/workflows/release-pkg.nu
index 9dac79402c..2044f644a8 100755
--- a/.github/workflows/release-pkg.nu
+++ b/.github/workflows/release-pkg.nu
@@ -122,7 +122,9 @@ print $'(char nl)All executable files:'; hr-line
 print (ls -f $executable); sleep 1sec
 
 print $'(char nl)Copying release files...'; hr-line
-cp -v README.release.txt $'($dist)/README.txt'
+"To use Nu plugins, use the register command to tell Nu where to find the plugin. For example:
+
+> register ./nu_plugin_query" | save $'($dist)/README.txt'
 [LICENSE $executable] | each {|it| cp -rv $it $dist } | flatten
 # Sleep a few seconds to make sure the cp process finished successfully
 sleep 3sec
diff --git a/Cargo.toml b/Cargo.toml
index 537c63d492..b159824785 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 authors = ["The Nushell Project Developers"]
+build = "scripts/build.rs"
 default-run = "nu"
 description = "A new type of shell"
 documentation = "https://www.nushell.sh/book/"
diff --git a/README.md b/README.md
index e3b5f92f7a..f06e3657fb 100644
--- a/README.md
+++ b/README.md
@@ -10,13 +10,14 @@
 
 A new type of shell.
 
-![Example of nushell](images/nushell-autocomplete6.gif "Example of nushell")
+![Example of nushell](assets/nushell-autocomplete6.gif "Example of nushell")
 
 ## Table of Contents <!-- omit in toc -->
 
 - [Status](#status)
 - [Learning About Nu](#learning-about-nu)
 - [Installation](#installation)
+- [Configuration](#configuration)
 - [Philosophy](#philosophy)
   - [Pipelines](#pipelines)
   - [Opening files](#opening-files)
@@ -55,6 +56,22 @@ Detailed installation instructions can be found in the [installation chapter of
 [![Packaging status](https://repology.org/badge/vertical-allrepos/nushell.svg)](https://repology.org/project/nushell/versions)
 
 
+## Configuration
+
+The default configurations can be found at [sample_config](crates/nu-utils/src/sample_config)
+which are the configuration files one gets when they startup Nushell for the first time.
+
+It sets all of the default configuration to run Nushell.  From here one can
+then customize this file for their specific needs.
+
+To see where *config.nu* is located on your system simply type this command.
+
+```rust
+$nu.config-path
+```
+
+Please see our [book](https://www.nushell.sh) for all of the Nushell documentation.
+
 
 ## Philosophy
 
diff --git a/README.release.txt b/README.release.txt
deleted file mode 100644
index 60951bb74e..0000000000
--- a/README.release.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-To use Nu plugins, use the register command to tell Nu where to find the plugin. For example:
-
-> register ./nu_plugin_query
diff --git a/images/nushell-autocomplete6.gif b/assets/nushell-autocomplete6.gif
similarity index 100%
rename from images/nushell-autocomplete6.gif
rename to assets/nushell-autocomplete6.gif
diff --git a/build-all.nu b/build-all.nu
deleted file mode 100644
index c1909e4a37..0000000000
--- a/build-all.nu
+++ /dev/null
@@ -1,25 +0,0 @@
-echo '-------------------------------------------------------------------'
-echo 'Building nushell (nu) with dataframes and all the plugins'
-echo '-------------------------------------------------------------------'
-
-echo $'(char nl)Building nushell'
-echo '----------------------------'
-cargo build --features=dataframe
-
-let plugins = [
-    nu_plugin_inc,
-    nu_plugin_gstat,
-    nu_plugin_query,
-    nu_plugin_example,
-    nu_plugin_custom_values,
-    nu_plugin_formats,
-]
-
-for plugin in $plugins {
-    $'(char nl)Building ($plugin)'
-    '----------------------------'
-    cd $'crates/($plugin)'
-    cargo build
-    cd ../../
-    ignore
-}
diff --git a/coverage-local.nu b/coverage-local.nu
deleted file mode 100755
index 887a7cbc41..0000000000
--- a/coverage-local.nu
+++ /dev/null
@@ -1,54 +0,0 @@
-#!/usr/bin/env nu
-
-let start = (date now)
-# Script to generate coverage locally
-#
-# Output: `lcov.info` file
-#
-# Relies on `cargo-llvm-cov`. Install via `cargo install cargo-llvm-cov`
-# https://github.com/taiki-e/cargo-llvm-cov
-
-# You probably have to run `cargo llvm-cov clean` once manually,
-# as you have to confirm to install additional tooling for your rustup toolchain.
-# Else the script might stall waiting for your `y<ENTER>`
-
-# Some of the internal tests rely on the exact cargo profile
-# (This is somewhat criminal itself)
-# but we have to signal to the tests that we use the `ci` `--profile`
-let-env NUSHELL_CARGO_TARGET = "ci"
-
-# Manual gathering of coverage to catch invocation of the `nu` binary.
-# This is relevant for tests using the `nu!` macro from `nu-test-support`
-# see: https://github.com/taiki-e/cargo-llvm-cov#get-coverage-of-external-tests
-
-print "Setting up environment variables for coverage"
-# Enable LLVM coverage tracking through environment variables
-# show env outputs .ini/.toml style description of the variables
-# In order to use from toml, we need to make sure our string literals are single quoted
-# This is especially important when running on Windows since "C:\blah" is treated as an escape
-cargo llvm-cov show-env | str replace (char dq) (char sq) -a | from toml | load-env
-
-print "Cleaning up coverage data"
-cargo llvm-cov clean --workspace
-
-print "Building with workspace and profile=ci"
-# Apparently we need to explicitly build the necessary parts
-# using the `--profile=ci` is basically `debug` build with unnecessary symbols stripped
-# leads to smaller binaries and potential savings when compiling and running
-cargo build --workspace --profile=ci
-
-print "Running tests with --workspace and profile=ci"
-cargo test --workspace --profile=ci
-
-# You need to provide the used profile to find the raw data
-print "Generating coverage report as lcov.info"
-cargo llvm-cov report --lcov --output-path lcov.info --profile=ci
-
-let end = (date now)
-$"Coverage generation took ($end - $start)."
-
-# To display the coverage in your editor see:
-#
-# - https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters
-# - https://github.com/umaumax/vim-lcov
-# - https://github.com/andythigpen/nvim-coverage (probably needs some additional config)
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 9ff29d0aad..0000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Documentation
-
-The default configurations can be found at [sample_config](../crates/nu-utils/src/sample_config)
-which are the configuration files one gets when they startup Nushell for the first time.
-
-It sets all of the default configuration to run Nushell.  From here one can
-then customize this file for their specific needs.
-
-To see where *config.nu* is located on your system simply type this command.
-
-```rust
-$nu.config-path
-```
-
-Please see our [book](https://www.nushell.sh) for all of the Nushell documentation.
diff --git a/pkg_mgrs/winget/0.17.yml b/pkg_mgrs/winget/0.17.yml
deleted file mode 100644
index 2e3ac01633..0000000000
--- a/pkg_mgrs/winget/0.17.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-Id: Nushell.Nushell
-Publisher: Nushell
-Name: Nushell
-Version: 0.17.0
-License: MIT
-LicenseUrl: https://github.com/nushell/nushell/blob/main/LICENSE
-AppMoniker: nushell
-Tags: shell, nu, nushell, functional, data, analysis
-Description: Nushell. A new type of shell.
-Homepage: https://www.nushell.sh/
-InstallerType: msi
-Installers:
-  - Arch: x64
-    Url: https://github.com/nushell/nushell/releases/download/0.17.0/nu_0_17_0_windows.msi
-    Sha256: 3EF3FCE4069510AD78577DC61E29F3DC02F4A384DE5E2CCD9D9862FC7E4D849E
-ManifestVersion: 0.1.0
\ No newline at end of file
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000000..366ff76375
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,27 @@
+## run the scripts
+
+> **Note**  
+> the following table must be read as follows:
+> - an `x` means *it works*
+> - a `?` means *no data available*
+>
+> `.nu` scripts must be run as `nu .../foo.nu`  
+> `.sh` scripts must be run as `./.../foo.sh`  
+> `.ps1` scripts must be run as `powershell .../foo.ps1`
+>
+> let's say a script is called `foo`
+> - an `x` in the *`./scripts`* column means *`foo` can be run from `./scripts`*
+> - an `x` in the *root* column means *`foo` can be run from the root of `nushell`*
+> - an `x` in the *anywhere* column means *`foo` can be run from anywhere!*
+
+| script                  | `./scripts/` | root | anywhere |
+| ----------------------- | ------------ | ---- | -------- |
+| `build-all-maclin.sh`   | x            | x    | x        |
+| `build-all-windows.cmd` | ?            | x    | ?        |
+| `build-all.nu`          | x            | x    | x        |
+| `coverage-local.nu`     | x            | x    | x        |
+| `coverage-local.sh`     | x            | x    | x        |
+| `install-all.ps1`       | ?            | x    | ?        |
+| `install-all.sh`        | x            | x    | x        |
+| `register-plugins.nu`   | x            | x    | x        |
+| `uninstall-all.sh`      | x            | x    | x        |
diff --git a/build-all-maclin.sh b/scripts/build-all-maclin.sh
similarity index 71%
rename from build-all-maclin.sh
rename to scripts/build-all-maclin.sh
index 45b0cac261..aad21d7b2a 100755
--- a/build-all-maclin.sh
+++ b/scripts/build-all-maclin.sh
@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
+
 set -euo pipefail
 
+DIR=$(readlink -f $(dirname "${BASH_SOURCE[0]}"))
+REPO_ROOT=$(dirname $DIR)
+
 echo "---------------------------------------------------------------"
 echo "Building nushell (nu) with dataframes and all the plugins"
 echo "---------------------------------------------------------------"
@@ -15,11 +19,17 @@ NU_PLUGINS=(
 )
 
 echo "Building nushell"
-cargo build --features=dataframe
+(
+    cd $REPO_ROOT
+    cargo build --features=dataframe
+)
+
 for plugin in "${NU_PLUGINS[@]}"
 do
-    echo '' && cd crates/"$plugin"
     echo "Building $plugin..."
     echo "-----------------------------"
-    cargo build && cd ../..
+    (
+        cd "$REPO_ROOT/crates/$plugin"
+        cargo build
+    )
 done
diff --git a/build-all-windows.cmd b/scripts/build-all-windows.cmd
similarity index 100%
rename from build-all-windows.cmd
rename to scripts/build-all-windows.cmd
diff --git a/scripts/build-all.nu b/scripts/build-all.nu
new file mode 100644
index 0000000000..71d896f983
--- /dev/null
+++ b/scripts/build-all.nu
@@ -0,0 +1,36 @@
+print '-------------------------------------------------------------------'
+print 'Building nushell (nu) with dataframes and all the plugins'
+print '-------------------------------------------------------------------'
+
+let repo_root = ($env.CURRENT_FILE | path dirname -n 2)
+
+def build-nushell [] {
+    print $'(char nl)Building nushell'
+    print '----------------------------'
+
+    cd $repo_root
+    cargo build --features=dataframe
+}
+
+def build-plugin [] {
+    let plugin = $in
+
+    print $'(char nl)Building ($plugin)'
+    print '----------------------------'
+
+    cd $'($repo_root)/crates/($plugin)'
+    cargo build
+}
+
+let plugins = [
+    nu_plugin_inc,
+    nu_plugin_gstat,
+    nu_plugin_query,
+    nu_plugin_example,
+    nu_plugin_custom_values,
+    nu_plugin_formats,
+]
+
+for plugin in $plugins {
+    $plugin | build-plugin
+}
diff --git a/build.rs b/scripts/build.rs
similarity index 100%
rename from build.rs
rename to scripts/build.rs
diff --git a/scripts/coverage-local.nu b/scripts/coverage-local.nu
new file mode 100755
index 0000000000..ed1350dc6e
--- /dev/null
+++ b/scripts/coverage-local.nu
@@ -0,0 +1,60 @@
+#!/usr/bin/env nu
+
+def compute-coverage [] {
+    cd ($env.CURRENT_FILE | path dirname -n 2)
+
+    print "Setting up environment variables for coverage"
+    # Enable LLVM coverage tracking through environment variables
+    # show env outputs .ini/.toml style description of the variables
+    # In order to use from toml, we need to make sure our string literals are single quoted
+    # This is especially important when running on Windows since "C:\blah" is treated as an escape
+    cargo llvm-cov show-env | str replace (char dq) (char sq) -a | from toml | load-env
+
+    print "Cleaning up coverage data"
+    cargo llvm-cov clean --workspace
+
+    print "Building with workspace and profile=ci"
+    # Apparently we need to explicitly build the necessary parts
+    # using the `--profile=ci` is basically `debug` build with unnecessary symbols stripped
+    # leads to smaller binaries and potential savings when compiling and running
+    cargo build --workspace --profile=ci
+
+    print "Running tests with --workspace and profile=ci"
+    cargo test --workspace --profile=ci
+
+    # You need to provide the used profile to find the raw data
+    print "Generating coverage report as lcov.info"
+    cargo llvm-cov report --lcov --output-path lcov.info --profile=ci
+}
+
+let start = (date now)
+# Script to generate coverage locally
+#
+# Output: `lcov.info` file
+#
+# Relies on `cargo-llvm-cov`. Install via `cargo install cargo-llvm-cov`
+# https://github.com/taiki-e/cargo-llvm-cov
+
+# You probably have to run `cargo llvm-cov clean` once manually,
+# as you have to confirm to install additional tooling for your rustup toolchain.
+# Else the script might stall waiting for your `y<ENTER>`
+
+# Some of the internal tests rely on the exact cargo profile
+# (This is somewhat criminal itself)
+# but we have to signal to the tests that we use the `ci` `--profile`
+let-env NUSHELL_CARGO_TARGET = "ci"
+
+# Manual gathering of coverage to catch invocation of the `nu` binary.
+# This is relevant for tests using the `nu!` macro from `nu-test-support`
+# see: https://github.com/taiki-e/cargo-llvm-cov#get-coverage-of-external-tests
+
+compute-coverage
+
+let end = (date now)
+print $"Coverage generation took ($end - $start)."
+
+# To display the coverage in your editor see:
+#
+# - https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters
+# - https://github.com/umaumax/vim-lcov
+# - https://github.com/andythigpen/nvim-coverage (probably needs some additional config)
diff --git a/coverage-local.sh b/scripts/coverage-local.sh
similarity index 60%
rename from coverage-local.sh
rename to scripts/coverage-local.sh
index d7f3cafbd1..fd05e10551 100755
--- a/coverage-local.sh
+++ b/scripts/coverage-local.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+DIR=$(readlink -f $(dirname "${BASH_SOURCE[0]}"))
+REPO_ROOT=$(dirname $DIR)
+
 # Script to generate coverage locally
 #
 # Output: `lcov.info` file
@@ -20,16 +23,19 @@ export NUSHELL_CARGO_TARGET=ci
 # This is relevant for tests using the `nu!` macro from `nu-test-support`
 # see: https://github.com/taiki-e/cargo-llvm-cov#get-coverage-of-external-tests
 
-# Enable LLVM coverage tracking through environment variables
-source <(cargo llvm-cov show-env --export-prefix)
-cargo llvm-cov clean --workspace
-# Apparently we need to explicitly build the necessary parts
-# using the `--profile=ci` is basically `debug` build with unnecessary symbols stripped
-# leads to smaller binaries and potential savings when compiling and running
-cargo build --workspace --profile=ci
-cargo test --workspace --profile=ci
-# You need to provide the used profile to find the raw data
-cargo llvm-cov report --lcov --output-path lcov.info --profile=ci
+(
+    cd $REPO_ROOT
+    # Enable LLVM coverage tracking through environment variables
+    source <(cargo llvm-cov show-env --export-prefix)
+    cargo llvm-cov clean --workspace
+    # Apparently we need to explicitly build the necessary parts
+    # using the `--profile=ci` is basically `debug` build with unnecessary symbols stripped
+    # leads to smaller binaries and potential savings when compiling and running
+    cargo build --workspace --profile=ci
+    cargo test --workspace --profile=ci
+    # You need to provide the used profile to find the raw data
+    cargo llvm-cov report --lcov --output-path lcov.info --profile=ci
+)
 
 # To display the coverage in your editor see:
 #
diff --git a/install-all.ps1 b/scripts/install-all.ps1
similarity index 100%
rename from install-all.ps1
rename to scripts/install-all.ps1
diff --git a/install-all.sh b/scripts/install-all.sh
similarity index 78%
rename from install-all.sh
rename to scripts/install-all.sh
index 8b9bcfc7b8..60629a73df 100755
--- a/install-all.sh
+++ b/scripts/install-all.sh
@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
-# Usage: Just run `./install-all.sh` in nushell root directory
+
 set -euo pipefail
 
+DIR=$(readlink -f $(dirname "${BASH_SOURCE[0]}"))
+REPO_ROOT=$(dirname $DIR)
+
 echo "-----------------------------------------------------------------"
 echo "Installing nushell (nu) with dataframes and all the plugins"
 echo "-----------------------------------------------------------------"
@@ -9,7 +12,7 @@ echo ""
 
 echo "Install nushell from local..."
 echo "----------------------------------------------"
-cargo install --force --path . --features=dataframe
+cargo install --force --path "$REPO_ROOT" --features=dataframe
 
 NU_PLUGINS=(
     'nu_plugin_inc'
@@ -26,5 +29,5 @@ do
     echo "----------------------------------------------"
     echo "Install plugin $plugin from local..."
     echo "----------------------------------------------"
-    cd crates/"$plugin" && cargo install --force --path . && cd ../../
+    cargo install --force --path "$REPO_ROOT/crates/$plugin"
 done
diff --git a/register-plugins.nu b/scripts/register-plugins.nu
similarity index 100%
rename from register-plugins.nu
rename to scripts/register-plugins.nu
diff --git a/uninstall-all.sh b/scripts/uninstall-all.sh
similarity index 100%
rename from uninstall-all.sh
rename to scripts/uninstall-all.sh