build: npm run compile-sass

TODO update ADR
TODO make compile-requirements
TODO testing

TODO: will copy in commit message from PR when squash-merging

Part of: TODO

docs/decisions/0017-reimplement-asset-processing.rst

@@ -128,9 +128,11 @@ The three top-level edx-platform asset processing actions are *build*, *collect*
 
        A Python-defined task that calls out to each build stage.
 
-     - ``scripts/build-assets.sh``
+     - ``npm clean-install && npm run build``
+
+       Simple NPM wrappers around the build stages. The wrappers will be written in Bash and tested on both GNU+Linux and macOS.
 
-       A Bash script that contains all build stages, with subcommands available for running each stage separately. Its command-line interface inspired by Tutor's ``openedx-assets`` script. The script will be runnable on any POSIX system, including macOS and Ubuntu and it will linted for common shell scripting mistakes using `shellcheck <https://www.shellcheck.net>`_.
+       These commands are a "one stop shop" for building assets, but more efficiency-oriented users may choose to run build stages individually.
 
    * - + **Build stage 1: Copy npm-installed assets** from node_modules to other folders in edx-platform. They are used by certain especially-old legacy LMS & CMS frontends that are not set up to work with npm directly.
 
@@ -174,27 +176,25 @@ The three top-level edx-platform asset processing actions are *build*, *collect*
 
        Note: libsass is pinned to a 2015 version with a non-trivial upgrade path. Installing it requires compiling a large C extension, noticeably affecting Docker image build time.
 
-     - ``scripts/build-assets.sh css``
+     - ``scripts/compile_sass``
 
-       Bash reimplementation, calling ``node-sass`` and ``rtlcss``.
+       TODO describe
 
-       The initial implementation of build-assets.sh may use ``sassc``, a CLI provided by libsass, instead of node-sass. Then, ``sassc`` can be replaced by ``node-sass`` as part of a subsequent `edx-platform frontend framework upgrade effort <https://github.com/openedx/edx-platform/issues/31616>`_.
+       TODO mention `edx-platform frontend framework upgrade effort <https://github.com/openedx/edx-platform/issues/31616>`_.
 
    * - + **Build stage 5: Compile themes' SCSS** into CSS for legacy LMS/CMS frontends. The default SCSS is used as a base, and theme-provided SCSS files are used as overrides. Themes are searched for from some number of operator-specified theme directories.
 
      - ``./manage.py [lms|cms] compile_sass``, or
 
-       ``paver compile_sass --theme-dirs ...``
+       ``paver compile_sass --theme-dirs X Y --themes A B``
 
        The management command is a wrapper around the paver task. The former looks up the list of theme search directories from Django settings and site configuration; the latter requires them to be supplied as arguments.
 
      - ``./manage.py [lms|cms] compile_sass``, or
 
-       ``scripts/build-assets.sh themes --theme-dirs ...``
-
-       The management command will remain available, but it will need to be updated to point at the Bash script, which will replace the paver task (see build stage 4 for details).
+     - ``scripts/compile_sass --theme-dir X --theme-dir  Y --theme A --theme B``
 
-       The overall asset *build* action will use the Bash script; this means that list of theme directories will need to be provided as arguments, but it ensures that the build can remain Python-free.
+       The management command will remain available, but it will need to be updated to point at ``compile_sass``, which will replace the paver task (see build stage 4 for details).
 
    * - **Collect** the built static assets from edx-platform to another location (the ``STATIC_ROOT``) so that they can be efficiently served *without* Django's webserver. This step, by nature, requires Python and Django in order to find and organize the assets, which may come from edx-platform itself or from its many installed Python and NPM packages. This is only needed for **production** environments, where it is usually desirable to serve assets with something efficient like NGINX.
 
@@ -313,9 +313,9 @@ Either way, the migration path is straightforward:
    * - ``openedx-assets xmodule``
      - (no longer needed)
    * - ``openedx-assets common``
-     - ``scripts/build-assets.sh css``
+     - ``compile_sass --skip-themes``
    * - ``openedx-assets themes``
-     - ``scripts/build-assets.sh themes``
+     - ``compile_sass --skip-default``
    * - ``openedx-assets webpack [--env=dev]``
      - ``npm run webpack[-dev]``
    * - ``openedx-assets collect``

package.json

@@ -4,8 +4,12 @@
   "repository": "https://github.com/openedx/edx-platform",
   "scripts": {
     "postinstall": "scripts/copy-node-modules.sh",
+    "build": "npm run webpack && npm run compile-sass",
+    "build-dev": "npm run webpack-dev && npm run compile-sass-dev",
     "webpack": "NODE_ENV=${NODE_ENV:-production} \"$(npm bin)/webpack\" --progress --config=${WEBPACK_CONFIG_PATH:-webpack.prod.config.js}",
-    "webpack-dev": "NODE_ENV=development WEBPACK_CONFIG_PATH=webpack.dev.config.js npm run webpack"
+    "webpack-dev": "NODE_ENV=development WEBPACK_CONFIG_PATH=webpack.dev.config.js npm run webpack",
+    "compile-sass": "compile_sass",
+    "compile-sass-dev": "compile_sass --env=dev"
   },
   "dependencies": {
     "@babel/core": "7.19.0",

requirements/constraints.txt

@@ -110,6 +110,11 @@ drf-yasg<1.21.6
 # Adding pin to avoid any major upgrade
 djangorestframework<3.15.0
 
-
 # tests failing with greater version. Fix this in separate ticket.
 pillow<10.0.0
+
+# Our legacy Sass code is incompatible with anything except this ancient libsass version.
+# Here is a ticket to upgrade, but it's of debatable importance given that we are rapidly moving
+# away from legacy LMS/CMS frontends:
+# https://github.com/openedx/edx-platform/issues/31616
+libsass==0.10.0

requirements/edx/assets.in

@@ -0,0 +1,5 @@
+-c constraints.txt
+
+click
+libsass
+nodeenv

requirements/edx/assets.txt

@@ -0,0 +1,3 @@
+click==8.1.5
+libsass==0.10.0
+nodeenv==1.8.0

requirements/edx/base.txt

@@ -676,10 +676,6 @@ lazy==1.5
     #   xblock
 learner-pathway-progress==1.3.4
     # via -r requirements/edx/bundled.in
-libsass==0.10.0
-    # via
-    #   -r requirements/edx/paver.txt
-    #   ora2
 loremipsum==1.0.5
     # via ora2
 lti-consumer-xblock==9.5.5
@@ -747,8 +743,6 @@ newrelic==8.8.1
     #   edx-django-utils
 nltk==3.8.1
     # via chem
-nodeenv==1.8.0
-    # via -r requirements/edx/kernel.in
 numpy==1.22.4
     # via
     #   chem

requirements/edx/development.in

@@ -13,6 +13,7 @@
 -r ../pip-tools.txt                     # pip-tools and its dependencies, for managing requirements files
 -r testing.txt                          # Dependencies for running the various test suites
 -r doc.txt                              # Dependencies for building the documentation locally.
+-r assets.txt                           # Dependencies for rebuilding static assets.
 
 click                                   # Used for perf_tests utilities in modulestore
 django-debug-toolbar                    # A set of panels that display debug information about the current request/response

requirements/edx/doc.txt

@@ -802,10 +802,6 @@ lazy==1.5
     #   xblock
 learner-pathway-progress==1.3.4
     # via -r requirements/edx/base.txt
-libsass==0.10.0
-    # via
-    #   -r requirements/edx/base.txt
-    #   ora2
 loremipsum==1.0.5
     # via
     #   -r requirements/edx/base.txt
@@ -887,8 +883,6 @@ nltk==3.8.1
     # via
     #   -r requirements/edx/base.txt
     #   chem
-nodeenv==1.8.0
-    # via -r requirements/edx/base.txt
 numpy==1.22.4
     # via
     #   -r requirements/edx/base.txt

requirements/edx/kernel.in

@@ -108,7 +108,6 @@ mako                                # Primary template language used for server-
 Markdown                            # Convert text markup to HTML; used in capa problems, forums, and course wikis
 mongoengine                         # Object-document mapper for MongoDB, used in the LMS dashboard
 mysqlclient                         # Driver for the default production relational database
-nodeenv                             # Utility for managing Node.js environments; we use this for deployments and testing
 oauthlib                            # OAuth specification support for authenticating via LTI or other Open edX services
 olxcleaner
 openedx-calc                        # Library supporting mathematical calculations for Open edX

requirements/edx/paver.in

@@ -12,7 +12,6 @@
 
 edx-opaque-keys                     # Create and introspect course and xblock identities
 lazy                                # Lazily-evaluated attributes for Python objects
-libsass==0.10.0                     # Python bindings for the LibSass CSS compiler
 markupsafe                          # XML/HTML/XHTML Markup safe strings
 mock                                # Stub out code with mock objects and make assertions about how they have been used
 path                                # Easier manipulation of filesystem paths

requirements/edx/paver.txt

@@ -16,8 +16,6 @@ idna==3.4
     # via requests
 lazy==1.5
     # via -r requirements/edx/paver.in
-libsass==0.10.0
-    # via -r requirements/edx/paver.in
 markupsafe==2.1.3
     # via -r requirements/edx/paver.in
 mock==5.1.0
@@ -43,7 +41,6 @@ requests==2.31.0
     # via -r requirements/edx/paver.in
 six==1.16.0
     # via
-    #   libsass
     #   paver
     #   python-memcached
 stevedore==5.1.0

requirements/edx/testing.txt

@@ -869,10 +869,6 @@ lazy-object-proxy==1.9.0
     # via astroid
 learner-pathway-progress==1.3.4
     # via -r requirements/edx/base.txt
-libsass==0.10.0
-    # via
-    #   -r requirements/edx/base.txt
-    #   ora2
 loremipsum==1.0.5
     # via
     #   -r requirements/edx/base.txt