Source: lib/traverse.js

  1. 'use strict';
  3. /**
  4.  * The `kss/lib/traverse` module is normally accessed via the
  5.  * [`traverse()`]{@link module:kss.traverse} method of the `kss` module:
  6.  * ```
  7.  * const kss = require('kss');
  8.  * let styleGuide = kss.traverse(directory, options);
  9.  * ```
  10.  * @private
  11.  * @module kss/lib/traverse
  12.  */
  14. const parse = require('./parse.js'),
  15.   path = require('path'),
  16.   Promise = require('bluebird');
  18. const fs = Promise.promisifyAll(require('fs-extra'));
  20. /**
  21.  * Traverse a directory, parse its contents, and create a KssStyleGuide.
  22.  *
  23.  * Callbacks receive an instance of `KssStyleGuide`.
  24.  *
  25.  * If you want to parse anything other than css, less, sass, or stylus files
  26.  * then you'll want to use options.mask to target a different set of file
  27.  * extensions.
  28.  *
  29.  * ```
  30.  * kss.traverse('./stylesheets', { mask: '*.css' }).then(function(styleGuide) {
  31.  *   styleGuide.sections('2.1.1') // <KssSection>
  32.  * });
  33.  * ```
  34.  *
  35.  * There a few extra `options` you can pass to `kss.traverse` which will effect
  36.  * the output:
  37.  *
  38.  * - mask: Use a regex or string (e.g. `*.less|*.css`) to only parse files
  39.  *   matching this value. Defaults to:
  40.  *   `*.css|*.less|*.sass|*.scss|*.styl|*.stylus`
  41.  * - markdown: kss-node supports built-in Markdown formatting of its
  42.  *   documentation, thanks to [markdown-it](https://markdown-it.github.io/). It's
  43.  *   enabled by default, but you can disable it by adding `markdown: false` to
  44.  *   the `options` object.
  45.  * - header: kss-node makes the header available separately from the
  46.  *   description. To make kss-node behave like the Ruby KSS, disable this option
  47.  *   and the title will remain a part of the description. This setting is
  48.  *   enabled by default, but you can disable it by adding `header: false` to
  49.  *   your options.
  50.  *
  51.  * @alias module:kss.traverse
  52.  * @param {String|Array} directories The directories to traverse
  53.  * @param {Object} [options] Options to alter the output content (optional)
  54.  * @returns {Promise} A `Promise` object resolving to a `KssStyleGuide`.
  55.  */
  56. let traverse = function(directories, options) {
  57.   options = options || {};
  59.   // Mask to search for particular file types - defaults to common precompilers.
  60.   options.mask = options.mask || /\.css|\.less|\.sass|\.scss|\.styl|\.stylus/;
  62.   // If the mask is a string, convert it into a RegExp.
  63.   if (!(options.mask instanceof RegExp)) {
  64.     options.mask = new RegExp(
  65.       '(?:' + options.mask.replace(/\./g, '\\.').replace(/\*/g, '.*') + ')$'
  66.     );
  67.   }
  69.   if (!Array.isArray(directories)) {
  70.     directories = [directories];
  71.   }
  73.   let walk = function(directory) {
  74.     // Look at the contents of the directory.
  75.     return fs.readdirAsync(directory).then(relnames => {
  76.       // If there are no files/folders, declare success.
  77.       if (relnames.length === 0) {
  78.         return Promise.resolve([]);
  79.       }
  81.       // Otherwise, loop through directory contents.
  82.       return Promise.all(
  83.         relnames.map(fileName => {
  84.           let name = path.join(directory, fileName);
  86.           // Check if the directory item is a directory or file.
  87.           return fs.statAsync(name).then(stat => {
  88.             // Recursively search any directories.
  89.             if (stat.isDirectory()) {
  90.               if (fileName !== '.svn' && fileName !== '.git') {
  91.                 return walk(name);
  92.               }
  93.             // If the file matches our mask, save its path.
  94.             } else if (!options.mask || name.match(options.mask)) {
  95.               return name;
  96.             }
  97.             return false;
  98.           });
  99.         })
  100.       ).then(results => {
  101.         // Flatten nested array result into a single array.
  102.         let files = [];
  103.         for (let result of results) {
  104.           if (Array.isArray(result)) {
  105.             for (let value of result) {
  106.               files.push(value);
  107.             }
  108.           } else if (result) {
  109.             files.push(result);
  110.           }
  111.         }
  112.         return files;
  113.       });
  114.     });
  115.   };
  117.   // Get each file in the target directory, order them alphabetically and then
  118.   // parse their output.
  120.   // Loop through all the given directories.
  121.   return Promise.all(
  122.     directories.map(directory => {
  123.       // Normalize the directory path and then "walk" it, collecting file names
  124.       // in the fileNames variable.
  125.       return walk(path.normalize(directory)).then(files => {
  126.         return {
  127.           base: directory,
  128.           files: files
  129.         };
  130.       });
  131.     })
  132.   ).then(results => {
  133.     // Flatten nested array result into a single array.
  134.     let files = [];
  135.     for (let directory of results) {
  136.       for (let file of directory.files) {
  137.         files.push({
  138.           base: directory.base,
  139.           path: file
  140.         });
  141.       }
  142.     }
  143.     return files;
  144.   }).then(files => {
  145.     // Read the contents of all the found file names.
  146.     return Promise.all(
  147.       files.map(file => {
  148.         return fs.readFileAsync(file.path, 'utf8').then(contents => {
  149.           file.contents = contents;
  150.           return file;
  151.         });
  152.       })
  153.     );
  154.   }).then(files => {
  155.     return parse(files, options);
  156.   });
  157. };
  159. module.exports = traverse;