feat(build-api): new, cleaner build-api

The build-api has been altered (and the internal build scripts have been updated accordingly). It
now only exposes paths and filenames that get distributed by the @buildit/gravity-ui-sass NPM
package.

BREAKING CHANGE: The build API is no longer the package's main entry point. You need to
`require('@buildit/gravity-ui-sass/build-api')` now. The available keys have also changed.

re #189

Author: James Nash

build-api.js

@@ -0,0 +1,153 @@
+/**
+ * Provides programatic access to CSS, asset and SASS file paths
+ * that are published by the gravity-ui-sass NPM package.
+ *
+ * This is so that consumers of this package can access those files
+ * in their own build processes (e.g. to copy them to their build dir)
+ * without needing to know the internal directory structure of this
+ * package or having to hard-code file paths in their own build
+ * scripts.
+ *
+ * @public
+ */
+
+// Note, since this file is included in the published NPM package, it
+// must not export paths or filenames that are excluded from the published
+// package. Refer to the 'files' section in package.json to see exactly
+// what gets published and what does not.
+// Any path or file data that is required for development and builds but
+// is excluded from the published NPM package should be added to
+// gulp/paths.js instead of this file.
+
+const path = require('path');
+const pkgManifest = require('./package.json');
+const bldConsts = require('./build-consts.js');
+
+const pkgDir = __dirname;
+
+
+// Resolves the given path segments relative to the UI lib dist dir
+function distPath(...pathSegements) {
+  return path.resolve(pkgDir, bldConsts.distDirname, bldConsts.uiLibDirname, ...pathSegements);
+}
+
+// CSS
+const distCssFileBasename = 'gravity';
+const distCssFilename = `${distCssFileBasename}.css`;
+
+const distCssDebugFileBasename = 'debug';
+const distCssDebugFilename = `${distCssDebugFileBasename}.css`;
+
+// SVG symbols
+const distSvgSymbolsFilename = `${bldConsts.svgSymbolsBasename}.svg`;
+const distSvgSymbolsInfoFilename = `${bldConsts.svgSymbolsBasename}.json`;
+
+// JS
+const distJsFileBasename = distCssFileBasename;
+const distJsFilename = `${distJsFileBasename}.js`;
+
+
+
+// Resolves the given path segments relative to the SASS src dir
+function srcSassPath(...pathSegements) {
+  return path.resolve(pkgDir, bldConsts.srcDirname, bldConsts.uiLibDirname, 'sass', ...pathSegements);
+}
+
+// SASS
+const srcSassMainFilename = 'index.scss';
+
+const srcSassDebugFilename = `${distCssDebugFileBasename}.scss`;
+
+
+
+module.exports = {
+  /**
+   * The Gravity UI SASS version.
+   *
+   * @public
+   */
+  version: pkgManifest.version,
+
+  // ==== Pre-compiled output: ====
+
+  /**
+   * Takes a sequence of path segments relative to the UI library's
+   * distributables directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the UI library's distributables directory.
+   *
+   * @return {string} Absolute file path to the specified
+   *        distributable directory or file.
+   *
+   * @public
+   */
+  distPath,
+
+  /**
+   * The filename of Gravity's pre-compiled CSS.
+   *
+   * @public
+   */
+  distCssFilename,
+
+  /**
+   * The filename of Gravity's pre-compiled debug CSS.
+   *
+   * @public
+   */
+  distCssDebugFilename,
+
+  /**
+   * The filename of Gravity's SVG symbols file.
+   *
+   * @public
+   */
+  distSvgSymbolsFilename,
+
+  /**
+   * The filename of Gravity's SVG symbols metadata JSON file.
+   *
+   * @public
+   */
+  distSvgSymbolsInfoFilename,
+
+  /**
+   * The filename of Gravity's client-side JS file.
+   *
+   * @public
+   */
+  distJsFilename,
+
+
+
+  // ==== Published source files: ====
+
+  /**
+   * Takes a sequence of path segments relative to the UI library's
+   * SASS source directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the UI library's SASS source directory.
+   *
+   * @return {string} Absolute file path to the specified source
+   *        directory or file.
+   *
+   * @public
+   */
+  srcSassPath,
+
+  /**
+   * The filename of Gravity's main SASS source file.
+   *
+   * @public
+   */
+  srcSassMainFilename,
+
+  /**
+   * The filename of Gravity's debug SASS source file.
+   *
+   * @public
+   */
+  srcSassDebugFilename,
+};

build-consts.js

@@ -0,0 +1,38 @@
+/**
+ * Shared constants used by public build-api and private build scripts.
+ *
+ * Although this is shipped as part of the NPM package, it is considered an
+ * internal ("private") API and is therefore not monitored for breaking changes.
+ *
+ * External consumers MUST NOT include this module.
+ *
+ * @private
+ */
+
+module.exports = {
+  /**
+   * Name of root source directory.
+   */
+  srcDirname: 'src',
+
+  /**
+   * Name of root distributables directory.
+   */
+  distDirname: 'dist',
+
+  /**
+   * Name of sub-directories containing UI library assets.
+   */
+  uiLibDirname: 'ui-lib',
+
+  /**
+   * Name of sub-directories containing pattern library assets.
+   */
+  patternLibDirname: 'styleguide',
+
+
+  /**
+   * Base filename used by various SVG symbols files.
+   */
+  svgSymbolsBasename: 'symbols',
+};

eyeglass-exports.js

@@ -1,7 +1,7 @@
-const { srcSassDir } = require('./index');
+const { srcSassPath } = require('./build-api.js');
 
 module.exports = function(eyeglass, sass) {
   return {
-    sassDir: srcSassDir,
+    sassDir: srcSassPath(),
   };
 };

gulp/paths.js

@@ -1,22 +1,87 @@
 /**
  * Export full set of file paths used by the build.
  *
- * Exports everything from index.js, which only exposes paths and files
+ * Exports everything from build-api.js, which only exposes paths and files
  * that are included in the published NPM package, and adds additional
  * paths and files that are only in the source repo but required for
  * builds.
  */
 const path = require('path');
-const pkgPaths = require('../index.js');
+const patternLabConfig = require('../patternlab-config.json');
+const bldConsts = require('../build-consts.js');
+
+const gulpDir = __dirname;
+
+// Resolves the given path segments relative to the package root dir
+function pkgRootPath(...pathSegements) {
+  return path.resolve(gulpDir, '..', ...pathSegements);
+}
+
+
+// ==== UI library ====
+
+function srcUiLibPath(...pathSegements) {
+  return pkgRootPath(bldConsts.srcDirname, bldConsts.uiLibDirname, ...pathSegements)
+}
+
+
+// ==== Pattern library ====
+
+// Resolves the given path segments relative to Pattern Lab's patterns source dir
+function srcPatternsPath(...pathSegments) {
+  return pkgRootPath(patternLabConfig.paths.source.patterns, ...pathSegments);
+}
+
+// Resolves the given path segments relative to the SASS src dir
+function distPatternLibPath(...pathSegements) {
+  return pkgRootPath(bldConsts.distDirname, bldConsts.patternLibDirname, ...pathSegements);
+}
 
-const srcImgDir = path.join(pkgPaths.srcUiLibDir, 'images');
-const srcSymbolsDir = path.join(pkgPaths.srcUiLibDir, 'svg-symbols');
-const srcJsDir = path.join(pkgPaths.srcUiLibDir, 'js');
 
 module.exports = {
-  srcImgDir,
-  srcSymbolsDir,
-  srcJsDir,
+  /**
+   * Takes a sequence of path segments relative to the package's
+   * root directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the package's root directory.
+   *
+   * @return {string} Absolute file path to the specified package
+   *        directory or file.
+   */
+  pkgRootPath,
+
+  /**
+   * Takes a sequence of path segments relative to the pattern
+   * library's source patterns directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the pattern library's source patterns directory.
+   *
+   * @return {string} Absolute file path to the specified source
+   *        directory or file.
+   */
+  srcPatternsPath,
+
+  /**
+   * Takes a sequence of path segments relative to the pattern
+   * library's distributables directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the pattern library's distributables directory.
+   *
+   * @return {string} Absolute file path to the specified distributable
+   *        directory or file.
+   */
+  distPatternLibPath,
+
+  /**
+   * The absolute path to SVG symbols source directory.
+   */
+  srcSvgSymbolsPath: (...pathSegments) => srcUiLibPath('svg-symbols', ...pathSegments),
 
-  ...pkgPaths
+  /**
+   * The absolute path to the JS source directory.
+   */
+  srcJsPath: (...pathSegments) => srcUiLibPath('js', ...pathSegments),
 }

gulp/patternlab.js

@@ -14,6 +14,8 @@ const eyeglass = require('eyeglass');
 const rename = require("gulp-rename");
 const path = require('path');
 const argv = require('minimist')(process.argv.slice(2));
+
+const uiLibPaths = require('../build-api.js');
 const pkgPaths = require('./paths.js');
 
 const taskNamePrefix = 'patternlab:';
@@ -22,9 +24,8 @@ const taskNamePrefix = 'patternlab:';
 const config = require('../patternlab-config.json');
 const patternlab = require('@pattern-lab/core')(config);
 
-function paths() {
-  return config.paths;
-}
+const plPaths = config.paths;
+
 
 /******************************************************
  * PRE-BUILD TASKS
@@ -35,29 +36,29 @@ function paths() {
 // Exported array of glob patterns that clean tasks can use to
 // delete any files generated at build-time
 const generatedFileGlobs = [
-  path.join(__dirname, '..', 'dependencyGraph.json'),
-  pkgPaths.normalizePath(paths().source.root, '_meta', '*.mustache')
+  pkgPaths.pkgRootPath('dependencyGraph.json'),
+  pkgPaths.pkgRootPath(plPaths.source.meta, '*.mustache')
 ];
 
-const generatedPatternsDir = pkgPaths.normalizePath(paths().source.patterns, '_generated');
-generatedFileGlobs.push(path.join(generatedPatternsDir, '*'));
-generatedFileGlobs.push('!' + path.join(generatedPatternsDir, 'README.md')); // Prevent README.md from being deleted
+const generatedPatternsDirname = '_generated';
+generatedFileGlobs.push(pkgPaths.srcPatternsPath(generatedPatternsDirname, '*'));
+generatedFileGlobs.push(`!${pkgPaths.srcPatternsPath(generatedPatternsDirname, 'README.md')}`); // Prevent README.md from being deleted
 
 function preSvgSymbolsTask () {
-  return gulp.src(pkgPaths.bldSvgSymbolsFilePath)
+  return gulp.src(uiLibPaths.distPath(uiLibPaths.distSvgSymbolsFilename))
     .pipe(rename('symbols.njk'))
-    .pipe(gulp.dest(generatedPatternsDir));
+    .pipe(gulp.dest(pkgPaths.srcPatternsPath(generatedPatternsDirname)));
 };
 preSvgSymbolsTask.displayName = taskNamePrefix + 'pre:symbols';
 preSvgSymbolsTask.description = 'Copies Gravity\'s symbols.svg file to the patterns folder.';
 
 
 const generatedSymbolInfoFilename = '00-svg-symbols.json';
-const generatedSymbolInfoDir = pkgPaths.normalizePath(paths().source.patterns, '00-particles', '05-logos-and-icons');
+const generatedSymbolInfoDir = pkgPaths.srcPatternsPath('00-particles', '05-logos-and-icons');
 generatedFileGlobs.push(path.join(generatedSymbolInfoDir, generatedSymbolInfoFilename));
 
 function preSvgSymbolsInfoTask () {
-  return gulp.src(pkgPaths.bldSvgSymbolsInfoFilePath)
+  return gulp.src(uiLibPaths.distPath(uiLibPaths.distSvgSymbolsInfoFilename))
     .pipe(rename(generatedSymbolInfoFilename))
     .pipe(gulp.dest(generatedSymbolInfoDir));
 };
@@ -72,9 +73,9 @@ const preBuildTask = gulp.parallel(preSvgSymbolsTask, preSvgSymbolsInfoTask);
 ******************************************************/
 
 function plSassTask() {
-  return gulp.src(pkgPaths.normalizePath(paths().source.root, 'sass', 'pattern-scaffolding.scss'))
+  return gulp.src(pkgPaths.pkgRootPath(plPaths.source.root, 'sass', 'pattern-scaffolding.scss'))
     .pipe(sass(eyeglass(sass.sync().on('error', sass.logError))))
-    .pipe(gulp.dest(pkgPaths.normalizePath(paths().public.css)))
+    .pipe(gulp.dest(pkgPaths.pkgRootPath(plPaths.public.css)))
 };
 plSassTask.displayName = taskNamePrefix + 'sass';
 plSassTask.description = 'Compiles pattern library CSS files from source SASS.';
@@ -158,7 +159,7 @@ plBuildTask.description = 'Compiles the patterns and frontend, outputting to con
 
 function plWatchSassTask() {
   gulp.watch(
-    pkgPaths.normalizePath(paths().source.root, 'sass', '**', '*.scss'),
+    pkgPaths.pkgRootPath(plPaths.source.root, 'sass', '**', '*.scss'),
     gulp.series(plSassTask, patternlab.server.refreshCSS)
   );
 }