@adamlui/scss-to-css 1.6.1 → 1.7.0

package/README.md

@@ -18,9 +18,9 @@
 
 ### Recursively compile all SCSS files into minified CSS.
 
-<a href="https://www.npmjs.com/package/@adamlui/scss-to-css"><img height=31 src="https://img.shields.io/npm/dt/%40adamlui%2Fscss-to-css?logo=npm&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="#%EF%B8%8F-mit-license"><img height=31 src="https://img.shields.io/badge/License-MIT-red.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=versions"><img height=31 src="https://img.shields.io/badge/Latest_Build-1.6.1-fc7811.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css"><img height=31 src="https://img.shields.io/npm/dt/%40adamlui%2Fscss-to-css?logo=npm&color=af68ff&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="#%EF%B8%8F-mit-license"><img height=31 src="https://img.shields.io/badge/License-MIT-orange.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=versions"><img height=31 src="https://img.shields.io/badge/Latest_Build-1.7.0-44cc11.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
 <a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/%40adamlui%2Fscss-to-css?style=for-the-badge&logo=ebox&logoColor=white&color=blue&labelColor=464646"></a>
 <a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:scss-to-css/scss-to-css.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Ascss-to-css%2Fscss-to-css.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=Vulnerabilities&color=gold"></a>
 
@@ -31,19 +31,19 @@
 As a **global utility**:
 
 ```
-npm install -g @adamlui/scss-to-css
+$ npm install -g @adamlui/scss-to-css
 ```
 
 As a **dev dependency** (e.g. for build scripts), from your project root:
 
 ```
-npm install -D @adamlui/scss-to-css
+$ npm install -D @adamlui/scss-to-css
 ```
 
 As a **runtime dependency** (e.g. for on-the-fly compilation), from your project root:
 
 ```
-npm install @adamlui/scss-to-css
+$ npm install @adamlui/scss-to-css
 ```
 
 ## 💻 Command line usage
@@ -51,7 +51,7 @@ npm install @adamlui/scss-to-css
 The basic **global command** is:
 
 ```
-scss-to-css
+$ scss-to-css
 ```
 
 Sample output:
@@ -65,7 +65,7 @@ Sample output:
 To specify **input/output** paths:
    
 ```
-scss-to-css [input_path] [output_path]
+$ scss-to-css [input_path] [output_path]
 ```
 
 - `[input_path]`: Path to SCSS file or directory containing SCSS files to be compiled, relative to the current working directory.
@@ -91,25 +91,25 @@ Replace `<scss-to-css-cmd>` with `scss-to-css` + optional args. Then, `npm run b
 Compile all SCSS files in the **current directory** (outputs to `css/`):
 
 ```
-scss-to-css
+$ scss-to-css
 ```
 
 Compile all SCSS files in a **specific directory** (outputs to `path/to/your/directory/css/`):
 
 ```
-scss-to-css path/to/your/directory
+$ scss-to-css path/to/your/directory
 ```
 
 Compile a **specific file** (outputs to `path/to/your/css/file.min.css`):
 
 ```
-scss-to-css path/to/your/file.scss
+$ scss-to-css path/to/your/file.scss
 ```
 
 Specify both **input and output** directories (outputs to `output_folder/`):
 
 ```
-scss-to-css input_folder output_folder
+$ scss-to-css input_folder output_folder
 ```
 
 **💡 Note:** Output CSS is minified unless `-M` or `--no-minify` is passed.
@@ -148,32 +148,35 @@ import * as scssToCSS from '@adamlui/scss-to-css';
 const scssToCSS = require('@adamlui/scss-to-css');
 ```
 
-### compile(inputPath, options)
+### `compile(inputPath[, options])`
 
-This function compiles SCSS found in the `inputPath` provided into CSS data.
+Compiles SCSS found in the `inputPath` provided into CSS data.
 
 If a **file path** is passed, the file's code is compiled to CSS, then an object containing `srcPath` + `code` + `error` is returned:
 
 ```js
 const compileResult = scssToCSS.compile('assets/style.scss');
-console.log(compileResult.error); // runtime error, or `undefined` if no error
-console.log(compileResult.code);  // compiled CSS output of assets/style.scss
+
+console.log(compileResult.error); // outputs runtime error, or `undefined` if no error
+console.log(compileResult.code);  // outputs compiled CSS from assets/style.scss
 ```
 
 If a **directory path** is passed, SCSS files are searched for (recursively by default), each one's code is loaded then compiled, then an array of objects containing `srcPath` + `code` + `error` is returned:
 
 ```js
+// Outputs paths to SCSS files in working directory + all nested directories
 const results = scssToCSS.compile('.');
-results.forEach(result =>
-    console.log(result.srcPath)); // paths to SCSS files in working directory + all nested directories
-console.log(results[1].code);     // compiled CSS output of 2nd SCSS file if found, or `undefined` if not found
+results.forEach(result => console.log(result.srcPath));
+
+// Outputs compiled CSS from 2nd SCSS file if found, or `undefined` if not found
+console.log(results[1].code);
 ```
 
 Options are boolean, passed as object properties. For example:
 
 ```js
+// Returns array of data objects where `.code` contains unminified CSS
 scssToCSS.compile(inputDir, { minify: false });
-// returns data objects where `.code` contains unminified CSS
 ```
 
 Possible parameters (and their default settings) are:
@@ -187,15 +190,15 @@ Possible parameters (and their default settings) are:
  sourceMaps (true)    Generate CSS source maps.
 ```
 
-### findSCSS(searchDir, options)
+### `findSCSS(searchDir[, options])`
 
-This function searches for all SCSS files within the `searchDir` string passed (useful for discovering what files [`compile()`](#compileinputpath-options) will process) and returns an array containing their filepaths.
+Searches for all SCSS files within the `searchDir` string passed (useful for discovering what files [`compile()`](#compileinputpath-options) will process) and returns an array containing their filepaths.
 
 Options are boolean, passed as object properties. For example:
 
 ```js
+// Returns array containing filepaths to SCSS files in exactly `searchDir`
 scssToCSS.findSCSS(searchDir, { recursive: false });
-// returns array containing filepaths to SCSS files in exactly `searchDir`
 ```
 
 Possible parameters (and their default settings) are:
@@ -203,7 +206,7 @@ Possible parameters (and their default settings) are:
 ```
  recursive (true)     Recursively search for nested files if dir path
                       passed.
- verbose (false)      Show logging in console/terminal.
+ verbose (true)       Show logging in console/terminal.
  dotFolders (false)   Include dotfolders in file search.
 ```
 
@@ -211,7 +214,7 @@ Possible parameters (and their default settings) are:
 
 ## 💖 Support
 
-Please consider [giving a GitHub ⭐](https://github.com/adamlui/js-utils) if this helped you!
+Please consider [giving a GitHub ⭐](https://github.com/adamlui/js-utils) or [funding](https://github.com/sponsors/adamlui) this project if it helped you!
 <br><br>
 
 ## 🏛️ MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamlui/scss-to-css",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Recursively compile all SCSS files into minified CSS",
   "author": {
     "name": "Adam Lui",

package/scss-to-css.js

@@ -8,29 +8,45 @@ const fs = require('fs'),
 // Define MAIN functions
 
 function findSCSS(searchDir, options = {}) {
-    const defaultOptions = { recursive: true, verbose: false, dotFolders: false };
-    options = { ...defaultOptions, ...options };        
+
+    // Init options
+    const defaultOptions = { recursive: true, verbose: true, dotFolders: false };
+    options = { ...defaultOptions, ...options };
+
+    // Search for SCSS
     const dirFiles = fs.readdirSync(searchDir), scssFiles = [];
+    if (options.verbose && !options.isRecursing) console.info('\nSearching for SCSS files...');
     dirFiles.forEach(file => {
         const filePath = path.resolve(searchDir, file);
         if (fs.statSync(filePath).isDirectory() && file != 'node_modules'
-            && (options.dotFolders || !file.startsWith('.')) && options.recursive) {
-                if (options.verbose) console.info(`Searching for SCSS files in: ${filePath}...`);
+            && (options.dotFolders || !file.startsWith('.')) && options.recursive)
                 scssFiles.push( // recursively find SCSS in eligible dir
                     ...findSCSS(filePath, { ...options, isRecursing: true }));
-        } else if (file.endsWith('.scss')) // SCSS file found
+        else if (file.endsWith('.scss')) // SCSS file found
             scssFiles.push(filePath); // store it for compilation
     });
-    if (options.isRecursing || scssFiles.length > 0) return scssFiles;
-    else if (options.verbose) console.info('\nNo SCSS files found.');
+
+    // Log/return final result
+    if (!options.isRecursing && options.verbose) {
+        console.info('Search complete. '
+            + ( scssFiles.length === 0 ? 'No' : scssFiles.length )
+            + ` file${ scssFiles.length > 1 ? 's' : '' } found.`);
+    }
+    return options.isRecursing || scssFiles.length > 0 ? scssFiles : [];
 }
 
 function compile(inputPath, options = {}) {
+
+    // Init options
     const defaultOptions = { minify: true, sourceMaps: true, recursive: true, verbose: true, dotFolders: false };
     options = { ...defaultOptions, ...options };
+
+    // Validate inputPath
     if (typeof inputPath !== 'string')
         return console.error('ERROR:'
             + ' First argument must be a string representing a file/folder path.');
+
+    // Compile SCSS based on inputPath
     const compileOptions = { style: options.minify ? 'compressed' : 'expanded', sourceMap: options.sourceMaps };
     if (fs.existsSync(inputPath)) { // compile based on path arg
         if (inputPath.endsWith('.scss')) { // file path passed
@@ -40,9 +56,9 @@ function compile(inputPath, options = {}) {
                 return { code: compileResult.css, srcMap: compileResult.sourceMap, srcPath: inputPath };
             } catch (err) { console.error(`\nERROR: ${ err.message }\n`); return { error: err }; }
         } else { // dir path passed
-            if (options.verbose) console.info('Searching for SCSS files...');
-            return findSCSS(inputPath, { recursive: options.recursive, dotFolders: options.dotFolders })
-                ?.map(scssPath => { // compile found SCSS files
+            return findSCSS(inputPath, { recursive: options.recursive, verbosity: options.verbose,
+                                         dotFolders: options.dotFolders
+                })?.map(scssPath => { // compile found SCSS files
                     if (options.verbose) console.info(`Compiling ${ scssPath }...`); 
                     try { // to compile found file
                         const compileResult = sass.compile(scssPath, compileOptions);
@@ -60,7 +76,7 @@ if (require.main !== module) module.exports = { compile, findSCSS };
 else { // run as CLI tool
 
     // Init UI colors
-    const nc = '\x1b[0m', // no color
+    const nc = '\x1b[0m',    // no color
           br = '\x1b[1;91m', // bright red
           by = '\x1b[1;33m', // bright yellow
           bg = '\x1b[1;92m'; // bright green
@@ -69,14 +85,14 @@ else { // run as CLI tool
     const config = { 
         dryRun: process.argv.some(arg => /^--?(?:n|dry-?run)$/.test(arg)),
         includeDotFolders: process.argv.some(arg =>
-            /^--?(?:dd?|(?:include-?)?dot-?(?:folder|dir(?:ector(?:y|ie))?)s?)$/.test(arg)),
+            /^--?(?:dd?|(?:include-?)?dot-?(?:folder|dir(?:ector(?:y|ie))?)s?=?(?:true|1)?)$/.test(arg)),
         noSourceMaps: process.argv.some(arg =>
-            /^--?(?:S|(?:exclude|disable|no)-?so?u?rce?-?maps?)$/.test(arg)),
+            /^--?(?:S|(?:exclude|disable|no)-?so?u?rce?-?maps?|so?u?rce?-?maps?=(?:false|0))$/.test(arg)),
         noRecursion: process.argv.some(arg =>
-            /^--?(?:R|(?:disable|no)-?recursion)$/.test(arg)),
+            /^--?(?:R|(?:disable|no)-?recursion|recursion=(?:false|0))$/.test(arg)),
         noMinify: process.argv.some(arg =>
-            /^--?(?:M|(?:disable|no)-?minif(?:y|ication))$/.test(arg)),
-        quietMode: process.argv.some(arg => /^--?q(?:uiet)?$/.test(arg))
+            /^--?(?:M|(?:disable|no)-?minif(?:y|ication)|minif(?:y|ication)=(?:false|0))$/.test(arg)),
+        quietMode: process.argv.some(arg => /^--?q(?:uiet)?(?:-?mode)?$/.test(arg))
     };
 
     // Show HELP screen if -h or --help passed
@@ -125,19 +141,20 @@ else { // run as CLI tool
         }
 
         // Find all eligible JavaScript files or arg-passed file
-        printIfNotQuiet('Searching for SCSS files...');
         const scssFiles = inputArg.endsWith('.scss') ? [inputPath]
-            : findSCSS(inputPath, { recursive: !config.noRecursion });
+            : findSCSS(inputPath, { recursive: !config.noRecursion, verbose: !config.quietMode });
 
-        if (config.dryRun && scssFiles?.length > 0) { // print files to be processed
-            console.info(`\n${by}SCSS files to be compiled:${nc}`);
-            scssFiles?.forEach(file => console.info(file));
+        if (config.dryRun) { // -n or --dry-run passed
+            if (scssFiles.length > 0) { // print files to be processed
+                console.info(`\n${by}SCSS files to be compiled:${nc}`);
+                scssFiles.forEach(file => console.info(file));
+            } else console.info(`${by}\nNo SCSS files will be compiled.${nc}`);
 
         } else { // actually compile SCSS files
 
             // Build array of compilation data
             const failedPaths = [];
-            const compileData = scssFiles?.map(scssPath => {
+            const compileData = scssFiles.map(scssPath => {
                 const compileResult = compile(scssPath, {
                     minify: !config.noMinify, sourceMaps: !config.noSourceMaps, verbose: !config.quietMode });
                 if (compileResult.error) failedPaths.push(scssPath);
@@ -170,7 +187,7 @@ else { // run as CLI tool
                 printIfNotQuiet(`${ compileData.length } CSS file${ cssCntSuffix }`
                     + ( !config.noSourceMaps ? ` + ${ compileData.length } source map${ cssCntSuffix }` : '' )
                     + ' generated.');
-            } else printIfNotQuiet(`${by}No SCSS files processed successfully.${nc}`);
+            } else printIfNotQuiet(`${by}No SCSS files processed.${nc}`);
             if (failedPaths.length > 0) {
                 printIfNotQuiet(`\n${br}`
                     + `${ failedPaths.length } file${ failedPaths.length > 1 ? 's' : '' }`