Version CLI

TACC · Mar 15, 2022 · 7c74248 · 7c74248
1 parent 9ca6af0
commit 7c74248
Show file tree

Hide file tree

Showing 9 changed files with 279 additions and 93 deletions.
diff --git a/README.md b/README.md
@@ -17,32 +17,92 @@ The shared styles for TACC WMA Workspace Portals & Websites
 #### CLI
 
 ```bash
-Usage: cli [options]
+Usage: core-styles [options] [command]
 
 Options:
-  -i, --input-dir <path>                parse CSS files from which directory
-  -o, --output-dir <path>               output CSS files to which directory
-  -e, --file-ext <ext>                  extension of CSS files to parse (default: "css") (default: "css")
-  -v, --version                         print the version of this software
-  --verbose                             print more information from build log
-  -c, --custom-config-files <paths...>  overwrite base config with values from YAML files¹² (advanced)
-  -h, --help                            display help for command
-
-Note:
-    The dir structure within '--input-dir' will be mirrored in '--output-dir'.
-
-Footnotes:
-    ¹ The file formats are like '.postcssrc.yml' from https://github.com/postcss/postcss-load-config#postcssrc.
-    ² The first file is merged on top of the base config.
-      Each successive file overwrites the file before it.
+  -V, --version      output the version number
+  -h, --help         display help for command
+
+Commands:
+  build [options]    build stylesheets with TACC standard process:
+  - "post-css" plugins
+  - custom input dir
+  - custom output dir
+  - custom configs
+
+  version [options]  create a stylesheet with preserved comment w/
+  - app name
+  - app version (via "git describe")
+  - app license
+  - custom output path
+
+  help [command]     display help for command
+```
+
+##### Build Command
+
+```bash
+Usage: core-styles build [options]
+
+build stylesheets with TACC standard process:
+- "post-css" plugins
+- custom input dir
+- custom output dir
+- custom configs
+
+
+Options:
+  -i, --input-dir <path>           parse source from which directory¹
+  -o, --output-dir <path>          output CSS files to which directory¹
+  -e, --file-ext <ext>             extensions to parse (default: "css")
+  -v, --verbose                    print more info during build process
+  -c, --custom-configs <paths...>  extend base config with YAML files²³
+  -h, --help                       display help for command
+
+Notes:
+  ¹ Folder structure of "--input-dir" mirrored in "--output-dir" e.g.
+
+    given input
+    - "input_dir/x.css"
+    - "input_dir/sub_dir_a/y.css"
+
+    expect output
+    - "output_dir/x.css"
+    - "output_dir/sub_dir_a/y.css"
+
+  ² The file formats are like ".postcssrc.yml" from
+    https://github.com/postcss/postcss-load-config#postcssrc
+
+  ³ The first file is merged on top of the base config.
+    Each successive file overwrites the file before it.
+```
+
+##### Version Command
+
+```bash
+Usage: core-styles version [options]
+
+create a stylesheet with preserved comment w/
+- app name
+- app version (via "git describe")
+- app license
+- custom output path
+
+
+Options:
+  -o, --output-path <path>  output version stylesheet at what path
+  -v, --verbose             print more info during file creation
+  -h, --help                display help for command
 ```
 
 #### Module
 
+##### Build Script
+
 ```js
-const coreStyles = require('core-styles');
+const buildStylesheets = require('core-styles');
 
-coreStyles(
+buildStylesheets(
   // Parse CSS files from which directory (required)
   `path/to/your/css/src`,
   // Output CSS files to which directory (required)
@@ -51,7 +111,7 @@ coreStyles(
     // (The first file is merged on top of the base config.)
     // (Each successive file overwrites the file before it.)
     // SEE: https://github.com/postcss/postcss-load-config#postcssrc
-    customConfigFiles: [
+    customConfigs: [
       // The "base" config is `/.postcssrc.base.yml`
       `path/to/custom/configthat/extends/base/.postcssrc.yml`,
       `path/to/custom/config/that/extends/above/.postcssrc.yml`
@@ -66,6 +126,19 @@ coreStyles(
 );
 ```
 
+##### Version Script
+
+```js
+const createVersionStylesheet = require('core-styles');
+
+createVersionStylesheet(
+  // Output version file at which path (required)
+  `path/to/put/_version.css`, {
+    // Print more info from build log (optional, default: false)
+    verbose: true
+  }
+);
+```
 
 ## Local Development Setup
 

diff --git a/bin/build.js b/bin/build.js
@@ -7,8 +7,10 @@ const cmd = require('node-cmd');
 // SEE: https://stackoverflow.com/a/63530170
 process.env.FORCE_COLOR = true
 
+
+
 /**
- * Build styles from external CSS
+ * Build stylesheets from source CSS
  * @param {string} inputDir - Parse CSS files from which directory
  * @param {string} outputDir - Output CSS files to which directory
  * @param {object} [opts={}] - Options
@@ -17,14 +19,21 @@ process.env.FORCE_COLOR = true
  * @param {boolean} [opts.verbose=false] - To print more info from build log
  */
 function build(inputDir, outputDir, opts = {}) {
+  // Get data
   const fileExt = opts.fileExt || 'css';
   const configDir = opts.configDir || `${__dirname}/../`;
   const verbose = (opts.verbose === true) ? '--verbose' : '';
 
+  // Build command
   const command = `postcss "${inputDir}/*.${fileExt}" --dir "${outputDir}" ${verbose} --config "${configDir}"`;
 
+  console.log(`Building stylesheets to ${outputDir}`);
+
+  // Run command
   cmd.runSync(command);
-  // console.log(command); // only shown if command execution is commented out
 }
 
+
+
+// Export
 module.exports = build;
diff --git a/bin/config.js b/bin/config.js
@@ -9,49 +9,61 @@ const yaml = require('js-yaml');
 const baseConfigFile = `${__dirname}/../.postcssrc.base.yml`;
 const newConfigFile = `${__dirname}/../.postcssrc.yml`;
 
+
+
 /**
  * Save base config as auto-loaded file (also can overwrite with custom values)
- * @param {array.string} [customConfigFiles] - List of YAML config files
+ * @param {array.string} [customConfigs] - List of YAML config file paths
  * (The first file is merged on top of the base config.)
  * (Each successive file overwrites the file before it.)
  * @see https://github.com/postcss/postcss-load-config#postcssrc
  */
-function config(customConfigFiles) {
+function config(customConfigs) {
+    // Get data
     let baseFile = baseConfigFile;
     let newYaml;
 
-    if (customConfigFiles) {
-        customConfigFiles.forEach(nextFile => {
+    // Either extend base config with any custom configs
+    if (customConfigs) {
+        customConfigs.forEach(nextFile => {
             if (nextFile && fs.existsSync(nextFile)) {
                 newYaml = getMergedConfig(baseFile, nextFile);
                 baseFile = newConfigFile;
             } else {
-              console.info(`Custom config ${nextFile} not found. Skipping`);
+              console.info(`Skipping custom config ${nextFile} (not found)`);
             }
         });
-    } else {
-        console.info('No custom files passed. Using only base config.');
+    }
+    // Or just use the base config
+    else {
+        console.info('Using only base config (no custom configs provided)');
         const baseConfig = fs.readFileSync(baseConfigFile, 'utf8');
         const baseJson = yaml.load(baseConfig);
         newYaml = yaml.dump(baseJson);
     }
 
+    // Write file
     fs.writeFileSync(newConfigFile, newYaml, 'utf8');
 }
 
+
+
 /**
  * Get content of merging one config file atop another
  * @param {array.string} baseFile - YAML config file to be extended
  * @param {array.string} customFile - YAML config file to merge onto base
  * @return {string} - Merged YAML
  */
  function getMergedConfig(baseFile, customFile) {
+    // Get data
     const baseConfig = fs.readFileSync(baseFile, 'utf8');
     const baseJson = yaml.load(baseConfig);
     const baseYaml = yaml.dump(baseJson);
 
+    // Default to base config content
     let newYaml = baseYaml;
 
+    // Any custom configs are merged onto the content
     if (customFile) {
         const customConfig = fs.readFileSync(customFile, 'utf8');
         const customJson = yaml.load(customConfig);
@@ -60,7 +72,11 @@ function config(customConfigFiles) {
         newYaml = yaml.dump(newJson);
     }
 
+    // Return content
     return newYaml;
 }
 
+
+
+// Export
 module.exports = config;
diff --git a/bin/update-version.js b/bin/update-version.js
diff --git a/bin/version.js b/bin/version.js
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/** Create CSS file to import that prints project version */
+
+const fs = require('fs');
+const path = require('../package.json');
+const childProcess = require('child_process');
+
+
+
+/**
+ * Create version stylesheet at specificed path
+ * @param {string} outputPath - Output version file at which path
+ */
+function create(outputPath) {
+    // Get data
+    const appName = process.env.npm_package_name;
+    const appLicense = path.license;
+    const appGitRef = childProcess.execSync('git describe --always').toString();
+    const fileContent = `/*! ${appName} ${appGitRef.replace("\n", "")} `
+                        + `| ${appLicense} | github.com/TACC/Core-Styles */`
+                        + "\n";
+
+    // Tell user
+    console.log(`Updating CSS version to ${appGitRef}`);
+
+    // Write version
+    fs.writeFileSync( outputPath, fileContent );
+}
+
+
+
+// Export
+module.exports = create;