Change How we are Rooting process directories & add path config

This PR adds a somewhat major change to how the pants-node plugin sets
up the environment in which it runs npm scripts. The goal is to better
support multiple projects with multiple package.jsons in a single
repo. The main necessary change is that we locate package.json with
the rest of the source files of the node_library instead of special
casing them.

a) Due to an issue with symlinks that was previously undiscovered due
to webpack behavior, we are no longer installing executables to the
`./node_modules/.bin` directory, this means the `'pants:build"` key in
the scripts object will need to call node directly with the path of
the executable script (e.g. `"node
node_modules/nuxt/bin/nuxt.js"` (this is what was symlinked
previously, but does not work with pants if the symlink references
relative paths) [More info
here](pantsbuild/pants#15211 (comment))

b) the previous code relied on package(-lock).json being in root of
the repository, this PR removes special handling of the
package(-lock).json files, they are now regular source files and part
of the `node_library` target

c) When running `npm run-script pants:build` the directory will
include all source files that have been re-rooted _to the node_package
target directory_ this means you can't meaningfully include files that
exist outside of the node_package directory in your build, I... don't
think this is a problem but it is something to keep in mind.

E.g. if before your node_package was defined in
src/delivery/dashboard/BUILD previously this plugin would evaluate
`npm run-script pants:build` in a directory containing package.json &
src/delivery/dsahboard/{all dependent source files & directories}
Now {all source files & directories} will be included in the
root (alongside package.json), this means that hopefully your
pants:build script is simpler/does not require weird configuration to
reach 3 directory layers deep.

d) source roots in output files will be stripped if the output_path is
not defined. This is so the bundles will overlay nicely with the
packaged python code, which generally strips source roots. If
output_path is defined output files will be directly appended to the
output_path value.

There is now a NodeSubsystem (pants terminology for configuration
settings) to allow configuration of how the pants-node plugin searches
for npm. Default configurations  are the same as previously except
/usr/local/bin is not searched by default. for more info run
`./pants help node` to display the full options & format

refrencing the changes above here's recommended process to upgrade
your targets to include these changes.

1) Include package.json & package-lock.json in your node_library
definitions.
2) update your 'pants:build' script key to directly reference the
appropriate executable
3) Make sure the output file path is correct & is included correctly
in the docker image you build

I have tested all this in the remit-srv codebase (that PR upcoming)
and it builds/includes both delivery dashboards successfully! You
truly can have it all.

README

@@ -20,18 +20,22 @@ backend_packages = ["sendwave.pants_node"]
 ### Usage
 
 This plugin adds two new targets to pants,
-* node_library which is analogous to python library and should contain all javascript, css, html, svg, etc etc files that will need to be operated on by your npm command. You can include all files in one node_library target or add other node_library targets as dependencicies. Unfortunately this does not hook into the `pants tailor`  command nor dependency tracking so you will need to manually specify dependencies or create single monster target
+* node_library: analogous to python library must contain all javascript, css, html, svg, etc etc files in its `sources` field. You can include all files in one node_library target or add other node_library targets as dependencicies. Unfortunately this does not hook into the `pants tailor`  command nor dependency tracking so you will need to manually specify dependencies or create single monster target
 
-* node_package, which should have a list of node_library dependencies, and a list of `artifact_paths`, and should be located in the same directory as your package.json & lock file, these will be automatically included in the build.
+* node_package, which should have a list of node_library dependencies, and a list of `artifact_paths`, those paths will be extracted from the build chroot & included in the package output.  NOTE: the package(-lock).json for your package must be included as a source file in one of the node_libary targets your node_package target depends on.
 
-The plugin will attempt to find your currently installed version of node and npm by searching your '/bin/`, `/usr/bin/` and `/usr/local/bin` paths as well as the value of the NVM_BIN environment variable.
+The plugin will attempt to find your currently installed version of node and npm by searching your '/bin/`, `/usr/bin/` paths as well as the value of the NVM_BIN environment variable, this behavior is configurable in the `[node]` scope of your pants.toml & via command line options. run `pants help node` for more information.
 
-It will install all dependencies as specified by the package.json file and constrainted by the lock file.
-Then it will run the npm script specified by the "pants:build" key in the context of all node_library source files.
+It will install all dependencies as specified by the package.json file and constrainted by the lock file (again: these must be included in a node_libary target!).
+Then it will run the npm script specified by the "pants:build" key in the context of all node_library source files. NOTE: due to how symlinks are handled in pants process output_digests you will not be able to reference the symlinked executable - the "pants:build" script should use node directly to evaluate the appropriate javascript file.
+Example:
+instead of "pants:build": "nuxt build" use "pants:build": "node node_modules/nuxt/bin/nuxt.js"
+
+For more information reference this github comment: https://github.com/pantsbuild/pants/pull/15211#issuecomment-1135155501
 
 All files under the `artifact_paths` will then be output in the pants-distdir (default `dist/`).
 
-You may include the built files in a `docker()` build target by including them as dependencies as normal
+You may include the built files in a `docker()` build target by including the node_package targets as dependencies to the docker target.
 
 NOTE:
 
@@ -40,7 +44,7 @@ Please make sure you have generated a package.lock file in order to have reprodu
 npm i --package-lock-only
 
 ### LICENSE
-See COPYING for the text of the Apache License which this package is released under 
+See COPYING for the text of the Apache License, which governs this package.
 
 
 [0] https://www.pantsbuild.org/

pants.toml

@@ -15,13 +15,14 @@ backend_packages = [
                  "sendwave.pants_node",
                  "sendwave.pants_docker"
                  ]
-
 [source]
-root_patterns = [
-              "/pants_plugins",
-              "/test_webpack",
-              ]
+root_patterns = ["/pants_plugins", "/test_webpack"]
+
+[node]
+use_nvm = true
 
+[python]
+interpreter_constraints = [">=3.9"]
 
 [anonymous-telemetry]
 enabled = true