application.ts

/**
 * The TypeDoc main module and namespace.
 *
 * The [[Application]] class holds the core logic of the cli application. All code related
 * to resolving reflections is stored in [[TypeDoc.Factories]], the actual data models can be found
 * in [[TypeDoc.Models]] and the final rendering is defined in [[TypeDoc.Output]].
 */

import * as Path from 'path';
import * as FS from 'fs';
import * as typescript from 'typescript';
import { Minimatch, IMinimatch } from 'minimatch';

import { Converter } from './converter/index';
import { Renderer } from './output/renderer';
import { Serializer } from './serialization';
import { ProjectReflection } from './models/index';
import { Logger, ConsoleLogger, CallbackLogger, PluginHost, writeFile } from './utils/index';

import { AbstractComponent, ChildableComponent, Component, Option } from './utils/component';
import { Options, OptionsReadMode, OptionsReadResult } from './utils/options/index';
import { ParameterType } from './utils/options/declaration';

/**
 * The default TypeDoc main application class.
 *
 * This class holds the two main components of TypeDoc, the [[Dispatcher]] and
 * the [[Renderer]]. When running TypeDoc, first the [[Dispatcher]] is invoked which
 * generates a [[ProjectReflection]] from the passed in source files. The
 * [[ProjectReflection]] is a hierarchical model representation of the TypeScript
 * project. Afterwards the model is passed to the [[Renderer]] which uses an instance
 * of [[BaseTheme]] to generate the final documentation.
 *
 * Both the [[Dispatcher]] and the [[Renderer]] are subclasses of the [[EventDispatcher]]
 * and emit a series of events while processing the project. Subscribe to these Events
 * to control the application flow or alter the output.
 */
@Component({name: 'application', internal: true})
export class Application extends ChildableComponent<Application, AbstractComponent<Application>> {
    options: Options;

    /**
     * The converter used to create the declaration reflections.
     */
    converter: Converter;

    /**
     * The renderer used to generate the documentation output.
     */
    renderer: Renderer;

    /**
     * The serializer used to generate JSON output.
     */
    serializer: Serializer;

    /**
     * The logger that should be used to output messages.
     */
    logger: Logger;

    plugins: PluginHost;

    @Option({
        name: 'logger',
        help: 'Specify the logger that should be used, \'none\' or \'console\'',
        defaultValue: 'console',
        type: ParameterType.Mixed
    })
    loggerType: string|Function;

    @Option({
        name: 'ignoreCompilerErrors',
        help: 'Should TypeDoc generate documentation pages even after the compiler has returned errors?',
        type: ParameterType.Boolean
    })
    ignoreCompilerErrors: boolean;

    @Option({
        name: 'exclude',
        help: 'Define patterns for excluded files when specifying paths.',
        type: ParameterType.Array
    })
    exclude: Array<string>;

    /**
     * The version number of TypeDoc.
     */
    static VERSION = '{{ VERSION }}';

    /**
     * Create a new TypeDoc application instance.
     *
     * @param options An object containing the options that should be used.
     */
    constructor(options?: Object) {
        super(null);

        this.logger    = new ConsoleLogger();
        this.converter = this.addComponent<Converter>('converter', Converter);
        this.serializer = this.addComponent<Serializer>('serializer', Serializer);
        this.renderer  = this.addComponent<Renderer>('renderer', Renderer);
        this.plugins   = this.addComponent('plugins', PluginHost);
        this.options   = this.addComponent('options', Options);

        this.bootstrap(options);
    }

    /**
     * Initialize TypeDoc with the given options object.
     *
     * @param options  The desired options to set.
     */
    protected bootstrap(options?: Object): OptionsReadResult {
        this.options.read(options, OptionsReadMode.Prefetch);

        const logger = this.loggerType;
        if (typeof logger === 'function') {
            this.logger = new CallbackLogger(<any> logger);
        } else if (logger === 'none') {
            this.logger = new Logger();
        }

        this.plugins.load();
        return this.options.read(this.options.getRawValues(), OptionsReadMode.Fetch);
    }

    /**
     * Return the application / root component instance.
     */
    get application(): Application {
        return this;
    }

    get isCLI(): boolean {
        return false;
    }

    /**
     * Return the path to the TypeScript compiler.
     */
    public getTypeScriptPath(): string {
        return Path.dirname(require.resolve('typescript'));
    }

    public getTypeScriptVersion(): string {
        const tsPath = this.getTypeScriptPath();
        const json = JSON.parse(FS.readFileSync(Path.join(tsPath, '..', 'package.json'), 'utf8'));
        return json.version;
    }

    /**
     * Run the converter for the given set of files and return the generated reflections.
     *
     * @param src  A list of source that should be compiled and converted.
     * @returns An instance of ProjectReflection on success, NULL otherwise.
     */
    public convert(src: string[]): ProjectReflection {
        this.logger.writeln('Using TypeScript %s from %s', this.getTypeScriptVersion(), this.getTypeScriptPath());

        const result = this.converter.convert(src);
        if (result.errors && result.errors.length) {
            this.logger.diagnostics(result.errors);
            if (this.ignoreCompilerErrors) {
                this.logger.resetErrors();
                return result.project;
            } else {
                return null;
            }
        } else {
            return result.project;
        }
    }

    /**
     * @param src  A list of source files whose documentation should be generated.
     */
    public generateDocs(src: string[], out: string): boolean;

    /**
     * @param project  The project the documentation should be generated for.
     */
    public generateDocs(project: ProjectReflection, out: string): boolean;

    /**
     * Run the documentation generator for the given set of files.
     *
     * @param out  The path the documentation should be written to.
     * @returns TRUE if the documentation could be generated successfully, otherwise FALSE.
     */
    public generateDocs(input: any, out: string): boolean {
        const project = input instanceof ProjectReflection ? input : this.convert(input);
        if (!project) {
            return false;
        }

        out = Path.resolve(out);
        this.renderer.render(project, out);
        if (this.logger.hasErrors()) {
            this.logger.error('Documentation could not be generated due to the errors above.');
        } else {
            this.logger.success('Documentation generated at %s', out);
        }

        return true;
    }

    /**
     * @param src  A list of source that should be compiled and converted.
     */
    public generateJson(src: string[], out: string): boolean;

    /**
     * @param project  The project that should be converted.
     */
    public generateJson(project: ProjectReflection, out: string): boolean;

    /**
     * Run the converter for the given set of files and write the reflections to a json file.
     *
     * @param out  The path and file name of the target file.
     * @returns TRUE if the json file could be written successfully, otherwise FALSE.
     */
    public generateJson(input: any, out: string): boolean {
        const project = input instanceof ProjectReflection ? input : this.convert(input);
        if (!project) {
            return false;
        }

        out = Path.resolve(out);
        const eventData = { outputDirectory: Path.dirname(out), outputFile: Path.basename(out) };
        const ser = this.serializer.projectToObject(project, { begin: eventData, end: eventData });
        writeFile(out, JSON.stringify(ser, null, '\t'), false);
        this.logger.success('JSON written to %s', out);

        return true;
    }

    /**
     * Expand a list of input files.
     *
     * Searches for directories in the input files list and replaces them with a
     * listing of all TypeScript files within them. One may use the ```--exclude``` option
     * to filter out files with a pattern.
     *
     * @param inputFiles  The list of files that should be expanded.
     * @returns  The list of input files with expanded directories.
     */
    public expandInputFiles(inputFiles?: string[]): string[] {
        let files: string[] = [];
        const exclude: Array<IMinimatch> = this.exclude ? this.exclude.map(pattern => new Minimatch(pattern)) : [];

        function isExcluded(fileName: string): boolean {
            return exclude.some(mm => mm.match(fileName));
        }

        function add(dirname: string) {
            FS.readdirSync(dirname).forEach((file) => {
                const realpath = Path.join(dirname, file);
                try {
                    if (FS.statSync(realpath).isDirectory()) {
                        add(realpath);
                    } else if (/\.tsx?$/.test(realpath)) {
                        if (isExcluded(realpath.replace(/\\/g, '/'))) {
                            return;
                        }
                        files.push(realpath);
                    }
                } catch (e) {}
            });
        }

        inputFiles.forEach((file) => {
            file = Path.resolve(file);
            try {
                if (FS.statSync(file).isDirectory()) {
                    add(file);
                } else if (!isExcluded(file)) {
                    files.push(file);
                }
            } catch (e) {}
        });

        return files;
    }

    /**
     * Print the version number.
     */
    public toString() {
        return [
            '',
            'TypeDoc ' + Application.VERSION,
            'Using TypeScript ' + this.getTypeScriptVersion() + ' from ' + this.getTypeScriptPath(),
            ''
        ].join(typescript.sys.newLine);
    }
}