publish.js

"use strict";

var fs = require("fs");

// output stream
var out = null;

// documentation data
var data = null;

// already handled objects, by name
var seen = {};

// indentation level
var indent = 0;

// whether indent has been written for the current line yet
var indentWritten = false;

// provided options
var options = {};

// queued interfaces
var queuedInterfaces = [];

// whether writing the first line
var firstLine = true;

// JSDoc hook
exports.publish = function publish(taffy, opts) {
    options = opts || {};

    // query overrides options
    if (options.query)
        Object.keys(options.query).forEach(function(key) {
            if (key !== "query")
                switch (options[key] = options.query[key]) {
                    case "true":
                        options[key] = true;
                        break;
                    case "false":
                        options[key] = false;
                        break;
                    case "null":
                        options[key] = null;
                        break;
                }
        });

    // remove undocumented
    taffy({ undocumented: true }).remove();
    taffy({ ignore: true }).remove();
    taffy({ inherited: true }).remove();

    // remove private
    if (!options.private)
        taffy({ access: "private" }).remove();

    // setup output
    out = options.destination
        ? fs.createWriteStream(options.destination)
        : process.stdout;

    try {
        // setup environment
        data = taffy().get();
        indent = 0;
        indentWritten = false;
        firstLine = true;

        // wrap everything in a module if configured
        if (options.module) {
            writeln("export = ", options.module, ";");
            writeln();
            writeln("declare namespace ", options.module, " {");
            writeln();
            ++indent;
        }

        // handle all
        getChildrenOf(undefined).forEach(function(child) {
            handleElement(child, null);
        });

        // process queued
        while (queuedInterfaces.length) {
            var element = queuedInterfaces.shift();
            begin(element);
            writeInterface(element);
            writeln(";");
        }

        // end wrap
        if (options.module) {
            --indent;
            writeln("}");
        }

        // close file output
        if (out !== process.stdout)
            out.end();

    } finally {
        // gc environment objects
        out = data = null;
        seen = options = {};
        queuedInterfaces = [];
    }
};

//
// Utility
//

// writes one or multiple strings
function write() {
    var s = Array.prototype.slice.call(arguments).join("");
    if (!indentWritten) {
        for (var i = 0; i < indent; ++i)
            s = "    " + s;
        indentWritten = true;
    }
    out.write(s);
    firstLine = false;
}

// writes zero or multiple strings, followed by a new line
function writeln() {
    var s = Array.prototype.slice.call(arguments).join("");
    if (s.length)
        write(s, "\n");
    else if (!firstLine)
        out.write("\n");
    indentWritten = false;
}

var keepTags = [
    "param",
    "returns",
    "throws",
    "see"
];

// parses a comment into text and tags
function parseComment(comment) {
    var lines = comment.replace(/^ *\/\*\* *|^ *\*\/| *\*\/ *$|^ *\* */mg, "").trim().split(/\r?\n|\r/g); // property.description has just "\r" ?!
    var desc;
    var text = [];
    var tags = null;
    for (var i = 0; i < lines.length; ++i) {
        var match = /^@(\w+)\b/.exec(lines[i]);
        if (match) {
            if (!tags) {
                tags = [];
                desc = text;
            }
            text = [];
            tags.push({ name: match[1], text: text });
            lines[i] = lines[i].substring(match[1].length + 1).trim();
        }
        if (lines[i].length || text.length)
            text.push(lines[i]);
    }
    return {
        text: desc || text,
        tags: tags || []
    };
}

// writes a comment
function writeComment(comment, otherwiseNewline) {
    if (!comment || options.comments === false) {
        if (otherwiseNewline)
            writeln();
        return;
    }
    if (typeof comment !== "object")
        comment = parseComment(comment);
    comment.tags = comment.tags.filter(function(tag) {
        return keepTags.indexOf(tag.name) > -1 && (tag.name !== "returns" || tag.text[0] !== "{undefined}");
    });
    writeln();
    if (!comment.tags.length && comment.text.length < 2) {
        writeln("/** " + comment.text[0] + " */");
        return;
    }
    writeln("/**");
    comment.text.forEach(function(line) {
        if (line.length)
            writeln(" * ", line);
        else
            writeln(" *");
    });
    comment.tags.forEach(function(tag) {
        var started = false;
        if (tag.text.length) {
            tag.text.forEach(function(line, i) {
                if (i > 0)
                    write(" * ");
                else if (tag.name !== "throws")
                    line = line.replace(/^\{[^\s]*} ?/, "");
                if (!line.length)
                    return;
                if (!started) {
                    write(" * @", tag.name, " ");
                    started = true;
                }
                writeln(line);
            });
        }
    });
    writeln(" */");
}

// recursively replaces all occurencies of re's match
function replaceRecursive(name, re, fn) {
    var found;

    function replacer() {
        found = true;
        return fn.apply(null, arguments);
    }

    do {
        found = false;
        name = name.replace(re, replacer);
    } while (found);
    return name;
}

// tests if an element is considered to be a class or class-like
function isClassLike(element) {
    return isClass(element) || isInterface(element);
}

// tests if an element is considered to be a class
function isClass(element) {
    return element && element.kind === "class";
}

// tests if an element is considered to be an interface
function isInterface(element) {
    return element && (element.kind === "interface" || element.kind === "mixin");
}

// tests if an element is considered to be a namespace
function isNamespace(element) {
    return element && (element.kind === "namespace" || element.kind === "module");
}

// gets all children of the specified parent
function getChildrenOf(parent) {
    var memberof = parent ? parent.longname : undefined;
    return data.filter(function(element) {
        return element.memberof === memberof;
    });
}

// gets the literal type of an element
function getTypeOf(element) {
    if (element.tsType)
        return element.tsType.replace(/\r?\n|\r/g, "\n");
    var name = "any";
    var type = element.type;
    if (type && type.names && type.names.length) {
        if (type.names.length === 1)
            name = element.type.names[0].trim();
        else
            name = "(" + element.type.names.join("|") + ")";
    } else
        return name;

    // Replace catchalls with any
    name = name.replace(/\*|\bmixed\b/g, "any");

    // Ensure upper case Object for map expressions below
    name = name.replace(/\bobject\b/g, "Object");

    // Correct Something.<Something> to Something<Something>
    name = replaceRecursive(name, /\b(?!Object|Array)([\w$]+)\.<([^>]*)>/gi, function($0, $1, $2) {
        return $1 + "<" + $2 + ">";
    });

    // Replace Array.<string> with string[]
    name = replaceRecursive(name, /\bArray\.?<([^>]*)>/gi, function($0, $1) {
        return $1 + "[]";
    });

    // Replace Object.<string,number> with { [k: string]: number }
    name = replaceRecursive(name, /\bObject\.?<([^,]*), *([^>]*)>/gi, function($0, $1, $2) {
        return "{ [k: " + $1 + "]: " + $2 + " }";
    });

    // Replace functions (there are no signatures) with Function
    name = name.replace(/\bfunction(?:\(\))?\b/g, "Function");

    // Convert plain Object back to just object
    name = name.replace(/\b(Object\b(?!\.))/g, function($0, $1) {
        return $1.toLowerCase();
    });

    return name;
}

// begins writing the definition of the specified element
function begin(element, is_interface) {
    if (!seen[element.longname]) {
        if (isClass(element)) {
            var comment = parseComment(element.comment);
            var classdesc = comment.tags.find(function(tag) { return tag.name === "classdesc"; });
            if (classdesc) {
                comment.text = classdesc.text;
                comment.tags = [];
            }
            writeComment(comment, true);
        } else
            writeComment(element.comment, is_interface || isClassLike(element) || isNamespace(element) || element.isEnum || element.scope === "global");
        seen[element.longname] = element;
    } else
        writeln();
    // ????: something changed in JSDoc 3.6.0? so that @exports + @enum does
    // no longer yield a 'global' scope, but is some sort of unscoped module
    // element now. The additional condition added below works around this.
    if ((element.scope === "global" || element.isEnum && element.scope === undefined) && !options.module)
        write("export ");
}

// writes the function signature describing element
function writeFunctionSignature(element, isConstructor, isTypeDef) {
    write("(");

    var params = {};

    // this type
    if (element.this)
        params["this"] = {
            type: element.this.replace(/^{|}$/g, ""),
            optional: false
        };

    // parameter types
    if (element.params)
        element.params.forEach(function(param) {
            var path = param.name.split(/\./g);
            if (path.length === 1)
                params[param.name] = {
                    type: getTypeOf(param),
                    variable: param.variable === true,
                    optional: param.optional === true,
                    defaultValue: param.defaultvalue // Not used yet (TODO)
                };
            else // Property syntax (TODO)
                params[path[0]].type = "{ [k: string]: any }";
        });

    var paramNames = Object.keys(params);
    paramNames.forEach(function(name, i) {
        var param = params[name];
        var type = param.type;
        if (param.variable) {
            name = "..." + name;
            type = param.type.charAt(0) === "(" ? "any[]" : param.type + "[]";
        }
        write(name, !param.variable && param.optional ? "?: " : ": ", type);
        if (i < paramNames.length - 1)
            write(", ");
    });

    write(")");

    // return type
    if (!isConstructor) {
        write(isTypeDef ? " => " : ": ");
        var typeName;
        if (element.returns && element.returns.length && (typeName = getTypeOf(element.returns[0])) !== "undefined")
            write(typeName);
        else
            write("void");
    }
}

// writes (a typedef as) an interface
function writeInterface(element) {
    write("interface ", element.name);
    writeInterfaceBody(element);
    writeln();
}

function writeInterfaceBody(element) {
    writeln("{");
    ++indent;
    if (element.tsType)
        writeln(element.tsType.replace(/\r?\n|\r/g, "\n"));
    else if (element.properties && element.properties.length)
        element.properties.forEach(writeProperty);
    --indent;
    write("}");
}

function writeProperty(property, declare) {
    writeComment(property.description);
    if (declare)
        write("let ");
    write(property.name);
    if (property.optional)
        write("?");
    writeln(": ", getTypeOf(property), ";");
}

//
// Handlers
//

// handles a single element of any understood type
function handleElement(element, parent) {
    if (element.scope === "inner")
        return false;

    if (element.optional !== true && element.type && element.type.names && element.type.names.length) {
        for (var i = 0; i < element.type.names.length; i++) {
            if (element.type.names[i].toLowerCase() === "undefined") {
                // This element is actually optional. Set optional to true and
                // remove the 'undefined' type
                element.optional = true;
                element.type.names.splice(i, 1);
                i--;
            }
        }
    }

    if (seen[element.longname])
        return true;
    if (isClassLike(element))
        handleClass(element, parent);
    else switch (element.kind) {
        case "module":
            if (element.isEnum) {
                handleEnum(element, parent);
                break;
            }
            // eslint-disable-line no-fallthrough
        case "namespace":
            handleNamespace(element, parent);
            break;
        case "constant":
        case "member":
            handleMember(element, parent);
            break;
        case "function":
            handleFunction(element, parent);
            break;
        case "typedef":
            handleTypeDef(element, parent);
            break;
        case "package":
            break;
    }
    seen[element.longname] = element;
    return true;
}

// handles (just) a namespace
function handleNamespace(element/*, parent*/) {
    var children = getChildrenOf(element);
    if (!children.length)
        return;
    var first = true;
    if (element.properties)
        element.properties.forEach(function(property) {
            if (!/^[$\w]+$/.test(property.name)) // incompatible in namespace
                return;
            if (first) {
                begin(element);
                writeln("namespace ", element.name, " {");
                ++indent;
                first = false;
            }
            writeProperty(property, true);
        });
    children.forEach(function(child) {
        if (child.scope === "inner" || seen[child.longname])
            return;
        if (first) {
            begin(element);
            writeln("namespace ", element.name, " {");
            ++indent;
            first = false;
        }
        handleElement(child, element);
    });
    if (!first) {
        --indent;
        writeln("}");
    }
}

// a filter function to remove any module references
function notAModuleReference(ref) {
    return ref.indexOf("module:") === -1;
}

// handles a class or class-like
function handleClass(element, parent) {
    var is_interface = isInterface(element);
    begin(element, is_interface);
    if (is_interface)
        write("interface ");
    else {
        if (element.virtual)
            write("abstract ");
        write("class ");
    }
    write(element.name);
    if (element.templates && element.templates.length)
        write("<", element.templates.join(", "), ">");
    write(" ");

    // extended classes
    if (element.augments) {
        var augments = element.augments.filter(notAModuleReference);
        if (augments.length)
            write("extends ", augments[0], " ");
    }

    // implemented interfaces
    var impls = [];
    if (element.implements)
        Array.prototype.push.apply(impls, element.implements);
    if (element.mixes)
        Array.prototype.push.apply(impls, element.mixes);
    impls = impls.filter(notAModuleReference);
    if (impls.length)
        write("implements ", impls.join(", "), " ");

    writeln("{");
    ++indent;

    if (element.tsType)
        writeln(element.tsType.replace(/\r?\n|\r/g, "\n"));

    // constructor
    if (!is_interface && !element.virtual)
        handleFunction(element, parent, true);

    // properties
    if (is_interface && element.properties)
        element.properties.forEach(function(property) {
            writeProperty(property);
        });

    // class-compatible members
    var incompatible = [];
    getChildrenOf(element).forEach(function(child) {
        if (isClassLike(child) || child.kind === "module" || child.kind === "typedef" || child.isEnum) {
            incompatible.push(child);
            return;
        }
        handleElement(child, element);
    });

    --indent;
    writeln("}");

    // class-incompatible members
    if (incompatible.length) {
        writeln();
        if (element.scope === "global" && !options.module)
            write("export ");
        writeln("namespace ", element.name, " {");
        ++indent;
        incompatible.forEach(function(child) {
            handleElement(child, element);
        });
        --indent;
        writeln("}");
    }
}

// handles an enum
function handleEnum(element) {
    begin(element);

    var stringEnum = false;
    element.properties.forEach(function(property) {
        if (isNaN(property.defaultvalue)) {
            stringEnum = true;
        }
    });
    if (stringEnum) {
        writeln("type ", element.name, " =");
        ++indent;
        element.properties.forEach(function(property, i) {
            write(i === 0 ? "" : "| ", JSON.stringify(property.defaultvalue));
        });
        --indent;
        writeln(";");
    } else {
        writeln("enum ", element.name, " {");
        ++indent;
        element.properties.forEach(function(property, i) {
            write(property.name);
            if (property.defaultvalue !== undefined)
                write(" = ", JSON.stringify(property.defaultvalue));
            if (i < element.properties.length - 1)
                writeln(",");
            else
                writeln();
        });
        --indent;
        writeln("}");
    }
}

// handles a namespace or class member
function handleMember(element, parent) {
    if (element.isEnum) {
        handleEnum(element);
        return;
    }
    begin(element);

    var inClass = isClassLike(parent);
    if (inClass) {
        write(element.access || "public", " ");
        if (element.scope === "static")
            write("static ");
        if (element.readonly)
            write("readonly ");
    } else
        write(element.kind === "constant" ? "const " : "let ");

    write(element.name);
    if (element.optional)
        write("?");
    write(": ");

    if (element.type && element.type.names && /^Object\b/i.test(element.type.names[0]) && element.properties) {
        writeln("{");
        ++indent;
        element.properties.forEach(function(property, i) {
            writeln(JSON.stringify(property.name), ": ", getTypeOf(property), i < element.properties.length - 1 ? "," : "");
        });
        --indent;
        writeln("};");
    } else
        writeln(getTypeOf(element), ";");
}

// handles a function or method
function handleFunction(element, parent, isConstructor) {
    var insideClass = true;
    if (isConstructor) {
        writeComment(element.comment);
        write("constructor");
    } else {
        begin(element);
        insideClass = isClassLike(parent);
        if (insideClass) {
            write(element.access || "public", " ");
            if (element.scope === "static")
                write("static ");
        } else
            write("function ");
        write(element.name);
        if (element.templates && element.templates.length)
            write("<", element.templates.join(", "), ">");
    }
    writeFunctionSignature(element, isConstructor, false);
    writeln(";");
    if (!insideClass)
        handleNamespace(element);
}

// handles a type definition (not a real type)
function handleTypeDef(element, parent) {
    if (isInterface(element)) {
        if (isClassLike(parent))
            queuedInterfaces.push(element);
        else {
            begin(element);
            writeInterface(element);
        }
    } else {
        writeComment(element.comment, true);
        write("type ", element.name);
        if (element.templates && element.templates.length)
            write("<", element.templates.join(", "), ">");
        write(" = ");
        if (element.tsType)
            write(element.tsType.replace(/\r?\n|\r/g, "\n"));
        else {
            var type = getTypeOf(element);
            if (element.type && element.type.names.length === 1 && element.type.names[0] === "function")
                writeFunctionSignature(element, false, true);
            else if (type === "object") {
                if (element.properties && element.properties.length)
                    writeInterfaceBody(element);
                else
                    write("{}");
            } else
                write(type);
        }
        writeln(";");
    }
}