src/sassdoc.js

import { denodeify, is, g2b } from './utils';

import Environment from './environment';
import Logger, { checkLogger } from './logger';
import Parser from './parser';
import * as errors from './errors';
import sorter from './sorter';
import exclude from './exclude';
import recurse from './recurse';

import fs from 'fs';
import path from 'path'; // jshint ignore:line
import difference from 'lodash.difference'; // jshint ignore:line
import safeWipe from 'safe-wipe';
import vfs from 'vinyl-fs';
import converter from 'sass-convert';
import pipe from 'multipipe'; // jshint ignore:line
import through from 'through2';
const mkdir = denodeify(require('mkdirp'));

/**
 * Expose lower API blocks.
 */
export { Environment, Logger, Parser, sorter, errors };

/**
 * Boostrap Parser and AnnotationsApi, execute parsing phase.
 * @return {Stream}
 * @return {Promise} - as a property of Stream.
 */
export function parseFilter(env = {}) {
  env = ensureEnvironment(env);

  let parser = new Parser(env, env.theme && env.theme.annotations);

  return parser.stream();
}

/**
 * Ensure a proper Environment Object and events.
 * @param {Object} config - can be falsy.
 * @return {Object}
 */
export function ensureEnvironment(config, onError = e => { throw e; }) {
  if (config instanceof Environment) {
    config.on('error', onError);
    return config;
  }

  let logger = ensureLogger(config);
  let env = new Environment(logger, config && config.strict);

  env.on('error', onError);
  env.load(config);
  env.postProcess();

  return env;
}

/**
 * @param {Object} config
 * @return {Logger}
 */
function ensureLogger(config) {
  if (!is.object(config) || !('logger' in config)) {
    // Get default logger.
    return new Logger(config && config.verbose, process.env.SASSDOC_DEBUG);
  }

  let logger = checkLogger(config.logger);
  delete config.logger;

  return logger;
}

/**
 * Default public API method.
 * @param {String | Array} src
 * @param {Object} env
 * @return {Promise | Stream}
 * @see srcEnv
 */
export default function sassdoc(...args) {
  return srcEnv(documentize, stream)(...args); // jshint ignore:line

  /**
   * Safely wipe and re-create the destination directory.
   * @return {Promise}
   */
  function refresh(env) { // jshint ignore:line
    return safeWipe(env.dest, {
      force: true,
      parent: is.string(env.src) || is.array(env.src) ? g2b(env.src) : null,
      silent: true,
    })
      .then(() => mkdir(env.dest))
      .then(() => {
        env.logger.log(`Folder \`${env.displayDest}\` successfully refreshed.`);
      })
      .catch(err => {
        // Friendly error for already existing directory.
        throw new errors.SassDocError(err.message);
      });
  }

  /**
   * Render theme with parsed data context.
   * @return {Promise}
   */
  function theme(env) { // jshint ignore:line
    let promise = env.theme(env.dest, env);

    if (!is.promise(promise)) {
      let type = Object.prototype.toString.call(promise);
      throw new errors.Error(`Theme didn't return a promise, got ${type}.`);
    }

    return promise
      .then(() => {
        let displayTheme = env.displayTheme || 'anonymous';
        env.logger.log(`Theme \`${displayTheme}\` successfully rendered.`);
      });
  }

  /**
   * Execute full SassDoc sequence from a source directory.
   * @return {Promise}
   */
  async function documentize(env) { // jshint ignore:line
    /* jshint ignore:start */

    init(env);
    let data = await baseDocumentize(env);

    try {
      await refresh(env);
      await theme(env);
      okay(env);
    } catch (err) {
      env.emit('error', err);
      throw err;
    }

    return data;

    /* jshint ignore:end */
  }

  /**
   * Execute full SassDoc sequence from a Vinyl files stream.
   * @return {Stream}
   * @return {Promise} - as a property of Stream.
   */
  function stream(env) {
    let filter = parseFilter(env);

    filter.promise
      .then(data => {
        env.logger.log('SCSS files successfully parsed.');
        env.data = data;
        onEmpty(data, env);
      });

    /* jshint ignore:start */

    /**
     * Returned Promise await the full sequence,
     * instead of just the parsing step.
     */
    filter.promise = new Promise((resolve, reject) => {

      async function documentize() {
        try {
          init(env);
          await refresh(env);
          await theme(env);
          okay(env);
          resolve();
        } catch (err) {
          reject(err);
          env.emit('error', err);
          throw err;
        }
      }

      filter
        .on('end', documentize)
        .on('error', err => env.emit('error', err))
        .resume(); // Drain.

    });

    /* jshint ignore:end */

    return filter;
  }
}

/**
 * Parse and return data object.
 * @param {String | Array} src
 * @param {Object} env
 * @return {Promise | Stream}
 * @see srcEnv
 */
export function parse(...args) { // jshint ignore:line
  /* jshint ignore:start */

  return srcEnv(documentize, stream)(...args);

  /**
   * @return {Promise}
   */
  async function documentize(env) {
    let data = await baseDocumentize(env);

    return data;
  }

  /* jshint ignore:end */

  /**
   * Don't pass files through, but pass final data at the end.
   * @return {Stream}
   */
  function stream(env) { // jshint ignore:line
    let parse = parseFilter(env);

    let filter = through.obj((file, enc, cb) => cb(), function (cb) {
      parse.promise.then(data => {
        this.push(data);
        cb();
      }, cb);
    });

    return pipe(parse, filter);
  }
}

/**
 * Source directory fetching and parsing.
 */
async function baseDocumentize(env) { // jshint ignore:line
  let filter = parseFilter(env);

  filter.promise
    .then(data => {
      env.logger.log(`Folder \`${env.src}\` successfully parsed.`);
      env.data = data;
      onEmpty(data, env);

      env.logger.debug(() => {
        fs.writeFile(
          'sassdoc-data.json',
          JSON.stringify(data, null, 2) + '\n'
        );

        return 'Dumping data to `sassdoc-data.json`.';
      });
    });

  let streams = [ // jshint ignore:line
    vfs.src(env.src),
    recurse(),
    exclude(env.exclude || []),
    converter({ from: 'sass', to: 'scss' }),
    filter
  ];

  /* jshint ignore:start */

  let pipeline = () => {
    return new Promise((resolve, reject) => {
      pipe(...streams, err => {
        err ? reject(err) : resolve();
      })
      .resume(); // Drain.
    });
  };

  try {
    await pipeline();
  } catch (err) {
    env.emit('error', err);
    throw err;
  }

  return env.data;

  /* jshint ignore:end */
}

/**
 * Return a function taking optional `src` string or array, and optional
 * `env` object (arguments are found by their type).
 *
 * If `src` is set, proxy to `documentize`, otherwise `stream`.
 *
 * Both functions will be passed the `env` object, which will have a
 * `src` key.
 */
function srcEnv(documentize, stream) {
  return function (...args) {
    let src = Array.find(args, a => is.string(a) || is.array(a));
    let env = Array.find(args, is.plainObject);

    env = ensureEnvironment(env);

    env.logger.debug('process.argv:', () => JSON.stringify(process.argv));
    env.logger.debug('sassdoc version:', () => require('../package.json').version);
    env.logger.debug('node version:', () => process.version.substr(1));

    env.logger.debug('npm version:', () => {
      let prefix = path.resolve(process.execPath, '../../lib');
      let pkg = path.resolve(prefix, 'node_modules/npm/package.json');

      try {
        return require(pkg).version;
      } catch (e) {
        return 'unknown';
      }
    });

    env.logger.debug('platform:', () => process.platform);
    env.logger.debug('cwd:', () => process.cwd());

    env.src = src;

    env.logger.debug('env:', () => {
      let clone = {};

      difference(
        Object.getOwnPropertyNames(env),
        ['domain', '_events', '_maxListeners', 'logger']
      )
        .forEach(k => clone[k] = env[k]);

      return JSON.stringify(clone, null, 2);
    });

    let task = env.src ? documentize : stream;
    env.logger.debug('task:', () => env.src ? 'documentize' : 'stream');

    return task(env);
  };
}

/**
 * Warn user on empty documentation.
 * @param {Array} data
 * @param {Object} env
 */
function onEmpty(data, env) {
  let message = `SassDoc could not find anything to document.\n
  * Are you still using \`/**\` comments ? They're no more supported since 2.0.
    See <http://sassdoc.com/upgrading/#c-style-comments>.
  * Are you documenting actual Sass items (variables, functions, mixins, placeholders) ?
    SassDoc doesn't support documenting CSS selectors.
    See <http://sassdoc.com/frequently-asked-questions/#does-sassdoc-support-css-classes-and-ids->.\n`;

  if (!data.length) {
    env.emit('warning', new errors.Warning(message));
  }
}

/**
 * Init timer.
 * @param {Object} env
 */
function init(env) { // jshint ignore:line
  env.logger.time('SassDoc');
}

/**
 * Log final success message.
 * @param {Object} env
 */
function okay(env) { // jshint ignore:line
  env.logger.log('Process over. Everything okay!');
  env.logger.timeEnd('SassDoc', '%s completed after %dms');
}