cli.js

/**
 * Helper methods for running JSDoc on the command line.
 *
 * A few critical notes for anyone who works on this module:
 *
 * + The module should really export an instance of `cli`, and `props` should be properties of a
 * `cli` instance. However, Rhino interpreted `this` as a reference to `global` within the
 * prototype's methods, so we couldn't do that.
 * + On Rhino, for unknown reasons, the `jsdoc/fs` and `jsdoc/path` modules can fail in some cases
 * when they are required by this module. You may need to use `fs` and `path` instead.
 *
 * @private
 */
module.exports = (function() {
'use strict';

var logger = require('jsdoc/util/logger');

var hasOwnProp = Object.prototype.hasOwnProperty;

var props = {
    docs: [],
    packageJson: null,
    shouldExitWithError: false,
    tmpdir: null
};

var app = global.app;
var env = global.env;

var FATAL_ERROR_MESSAGE = 'Exiting JSDoc because an error occurred. See the previous log ' +
    'messages for details.';
var cli = {};

// TODO: docs
cli.setVersionInfo = function() {
    var fs = require('fs');
    var path = require('path');

    // allow this to throw--something is really wrong if we can't read our own package file
    var info = JSON.parse( fs.readFileSync(path.join(env.dirname, 'package.json'), 'utf8') );

    env.version = {
        number: info.version,
        revision: new Date( parseInt(info.revision, 10) ).toUTCString()
    };

    return cli;
};

// TODO: docs
cli.loadConfig = function() {
    var _ = require('underscore');
    var args = require('jsdoc/opts/args');
    var Config = require('jsdoc/config');
    var fs = require('jsdoc/fs');
    var path = require('jsdoc/path');

    var confPath;
    var isFile;

    var defaultOpts = {
        destination: './out/',
        encoding: 'utf8'
    };

    try {
        env.opts = args.parse(env.args);
    }
    catch (e) {
        cli.exit(1, e.message + '\n' + FATAL_ERROR_MESSAGE);
    }

    confPath = env.opts.configure || path.join(env.dirname, 'conf.json');
    try {
        isFile = fs.statSync(confPath).isFile();
    }
    catch(e) {
        isFile = false;
    }

    if ( !isFile && !env.opts.configure ) {
        confPath = path.join(env.dirname, 'conf.json.EXAMPLE');
    }

    try {
        env.conf = new Config( fs.readFileSync(confPath, 'utf8') )
            .get();
    }
    catch (e) {
        cli.exit(1, 'Cannot parse the config file ' + confPath + ': ' + e + '\n' +
            FATAL_ERROR_MESSAGE);
    }

    // look for options on the command line, in the config file, and in the defaults, in that order
    env.opts = _.defaults(env.opts, env.conf.opts, defaultOpts);

    return cli;
};

// TODO: docs
cli.configureLogger = function() {
    function recoverableError() {
        props.shouldExitWithError = true;
    }

    function fatalError() {
        cli.exit(1);
    }

    if (env.opts.debug) {
        logger.setLevel(logger.LEVELS.DEBUG);
    }
    else if (env.opts.verbose) {
        logger.setLevel(logger.LEVELS.INFO);
    }

    if (env.opts.pedantic) {
        logger.once('logger:warn', recoverableError);
        logger.once('logger:error', fatalError);
    }
    else {
        logger.once('logger:error', recoverableError);
    }

    logger.once('logger:fatal', fatalError);

    return cli;
};

// TODO: docs
cli.logStart = function() {
    logger.debug( cli.getVersion() );

    logger.debug('Environment info: %j', {
        env: {
            conf: env.conf,
            opts: env.opts
        }
    });
};

// TODO: docs
cli.logFinish = function() {
    var delta;
    var deltaSeconds;

    if (env.run.finish && env.run.start) {
        delta = env.run.finish.getTime() - env.run.start.getTime();
    }

    if (delta !== undefined) {
        deltaSeconds = (delta / 1000).toFixed(2);
        logger.info('Finished running in %s seconds.', deltaSeconds);
    }
};

// TODO: docs
cli.runCommand = function(cb) {
    var cmd;

    var opts = env.opts;

    function done(errorCode) {
        if (!errorCode && props.shouldExitWithError) {
            cb(1);
        }
        else {
            cb(errorCode);
        }
    }

    if (opts.help) {
        cmd = cli.printHelp;
    }
    else if (opts.test) {
        cmd = cli.runTests;
    }
    else if (opts.version) {
        cmd = cli.printVersion;
    }
    else {
        cmd = cli.main;
    }

    cmd(done);
};

// TODO: docs
cli.printHelp = function(cb) {
    cli.printVersion();
    console.log( '\n' + require('jsdoc/opts/args').help() + '\n' );
    console.log('Visit http://usejsdoc.org for more information.');
    cb(0);
};

// TODO: docs
cli.runTests = function(cb) {
    var path = require('jsdoc/path');

    var runner = require( path.join(env.dirname, 'test/runner') );

    console.log('Running tests...');
    runner(function(failCount) {
        cb(failCount);
    });
};

// TODO: docs
cli.getVersion = function() {
    return 'JSDoc ' + env.version.number + ' (' + env.version.revision + ')';
};

// TODO: docs
cli.printVersion = function(cb) {
    console.log( cli.getVersion() );

    if (cb) {
        cb(0);
    }
};

// TODO: docs
cli.main = function(cb) {
    cli.scanFiles();

    if (env.sourceFiles.length) {
        cli.createParser()
            .parseFiles()
            .processParseResults();
    }

    env.run.finish = new Date();
    cb(0);
};

function getRandomId() {
    var MIN = 100000;
    var MAX = 999999;

    return Math.floor(Math.random() * (MAX - MIN + 1) + MIN);
}

// TODO: docs
function createTempDir() {
    var fs = require('jsdoc/fs');
    var path = require('jsdoc/path');
    var wrench = require('wrench');

    var isRhino;
    var tempDirname;
    var tempPath;

    // We only need one temp directory
    if (props.tmpdir) {
        return props.tmpdir;
    }

    isRhino = require('jsdoc/util/runtime').isRhino();
    tempDirname = 'tmp-' + Date.now() + '-' + getRandomId();
    tempPath = path.join(env.dirname, tempDirname);

    try {
        fs.mkdirSync(tempPath);
        props.tmpdir = tempPath;
    }
    catch (e) {
        logger.fatal('Unable to create the temp directory %s: %s', tempPath, e.message);
        return null;
    }

    try {
        // Delete the temp directory on exit
        if (isRhino) {
            ( new java.io.File(tempPath) ).deleteOnExit();
        }
        else {
            process.on('exit', function() {
                wrench.rmdirSyncRecursive(tempPath);
            });
        }

        return tempPath;
    }
    catch (e) {
        logger.error('Cannot automatically delete the temp directory %s on exit: %s', tempPath,
            e.message);
        return null;
    }
}

// TODO: docs
function copyResourceDir(filepath) {
    var fs = require('jsdoc/fs');
    var path = require('jsdoc/path');
    var wrench = require('wrench');

    var resourceDir;
    var tmpDir;

    try {
        tmpDir = createTempDir();
        resourceDir = path.join( tmpDir, path.basename(filepath) + '-' + getRandomId() );
        fs.mkdirSync(resourceDir);

        wrench.copyDirSyncRecursive(filepath, resourceDir);
        return resourceDir;
    }
    catch (e) {
        logger.fatal('Unable to copy %s to the temp directory %s: %s', filepath, resourceDir,
            e.message);
        return null;
    }
}

// TODO: docs
cli.scanFiles = function() {
    var Filter = require('jsdoc/src/filter').Filter;
    var fs = require('jsdoc/fs');
    var Readme = require('jsdoc/readme');

    var filter;
    var opt;

    if (env.conf.source && env.conf.source.include) {
        env.opts._ = (env.opts._ || []).concat(env.conf.source.include);
    }

    // source files named `package.json` or `README.md` get special treatment
    for (var i = 0, l = env.opts._.length; i < l; i++) {
        opt = env.opts._[i];

        if ( /\bpackage\.json$/i.test(opt) ) {
            props.packageJson = fs.readFileSync(opt, 'utf8');
            env.opts._.splice(i--, 1);
        }

        if ( /(\bREADME|\.md)$/i.test(opt) ) {
            env.opts.readme = new Readme(opt).html;
            env.opts._.splice(i--, 1);
        }
    }

    // are there any files to scan and parse?
    if (env.conf.source && env.opts._.length) {
        filter = new Filter(env.conf.source);

        env.sourceFiles = app.jsdoc.scanner.scan(env.opts._, (env.opts.recurse? 10 : undefined),
            filter);
    }

    return cli;
};

function resolvePluginPaths(paths) {
    var path = require('jsdoc/path');

    var isNode = require('jsdoc/util/runtime').isNode();
    var pluginPaths = [];

    paths.forEach(function(plugin) {
        var basename = path.basename(plugin);
        var dirname = path.dirname(plugin);
        var pluginPath = path.getResourcePath(dirname);

        if (!pluginPath) {
            logger.error('Unable to find the plugin "%s"', plugin);
            return;
        }
        // On Node.js, the plugin needs to be inside the JSDoc directory
        else if ( isNode && (pluginPath.indexOf(global.env.dirname) !== 0) ) {
            pluginPath = copyResourceDir(pluginPath);
        }

        pluginPaths.push( path.join(pluginPath, basename) );
    });

    return pluginPaths;
}

cli.createParser = function() {
    var handlers = require('jsdoc/src/handlers');
    var parser = require('jsdoc/src/parser');
    var path = require('jsdoc/path');
    var plugins = require('jsdoc/plugins');

    app.jsdoc.parser = parser.createParser(env.conf.parser);

    if (env.conf.plugins) {
        env.conf.plugins = resolvePluginPaths(env.conf.plugins);
        plugins.installPlugins(env.conf.plugins, app.jsdoc.parser);
    }

    handlers.attachTo(app.jsdoc.parser);

    return cli;
};

cli.parseFiles = function() {
    var augment = require('jsdoc/augment');
    var borrow = require('jsdoc/borrow');
    var Package = require('jsdoc/package').Package;

    var docs;
    var packageDocs;

    props.docs = docs = app.jsdoc.parser.parse(env.sourceFiles, env.opts.encoding);

    // If there is no package.json, just create an empty package
    packageDocs = new Package(props.packageJson);
    packageDocs.files = env.sourceFiles || [];
    docs.push(packageDocs);

    logger.debug('Adding inherited symbols...');
    borrow.indexAll(docs);
    augment.addInherited(docs);
    borrow.resolveBorrows(docs);

    app.jsdoc.parser.fireProcessingComplete(docs);

    return cli;
};

cli.processParseResults = function() {
    if (env.opts.explain) {
        cli.dumpParseResults();
    }
    else {
        cli.resolveTutorials();
        cli.generateDocs();
    }

    return cli;
};

cli.dumpParseResults = function() {
    global.dump(props.docs);

    return cli;
};

cli.resolveTutorials = function() {
    var resolver = require('jsdoc/tutorial/resolver');

    if (env.opts.tutorials) {
        resolver.load(env.opts.tutorials);
        resolver.resolve();
    }

    return cli;
};

cli.generateDocs = function() {
    var path = require('jsdoc/path');
    var resolver = require('jsdoc/tutorial/resolver');
    var taffy = require('taffydb').taffy;

    var template;

    env.opts.template = (function() {
        var isNode = require('jsdoc/util/runtime').isNode();
        var publish = env.opts.template || 'templates/default';
        var templatePath = path.getResourcePath(publish);

        if (templatePath && isNode) {
            // On Node.js, the template needs to be inside the JSDoc folder
            if (templatePath.indexOf(env.dirname) !== 0) {
                templatePath = copyResourceDir(templatePath);
            }
        }

        // if we didn't find the template, keep the user-specified value so the error message is
        // useful
        return templatePath || env.opts.template;
    })();

    try {
        template = require(env.opts.template + '/publish');
    }
    catch(e) {
        logger.fatal('Unable to load template: ' + e.message || e);
    }

    // templates should include a publish.js file that exports a "publish" function
    if (template.publish && typeof template.publish === 'function') {
        logger.printInfo('Generating output files...');
        template.publish(
            taffy(props.docs),
            env.opts,
            resolver.root
        );
        logger.info('complete.');
    }
    else {
        logger.fatal(env.opts.template + ' does not export a "publish" function. Global ' +
            '"publish" functions are no longer supported.');
    }

    return cli;
};

// TODO: docs
cli.exit = function(exitCode, message) {
    if (message && exitCode > 0) {
        console.error(message);
    }

    process.exit(exitCode || 0);
};

return cli;

})();