@depup/apollo__protobufjs 1.2.7-depup.0

package/cli/lib/tsd-jsdoc/publish.js

@@ -0,0 +1,693 @@
+"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();
+    if (element.scope !== "global" || options.module)
+        return;
+    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":
+        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 a namespace or class member
+function handleMember(element, parent) {
+    begin(element);
+
+    if (element.isEnum) {
+        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("}");
+        }
+
+    } else {
+
+        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(";");
+    }
+}

package/cli/lib/tsd-jsdoc.json

@@ -0,0 +1,18 @@
+{
+    "tags": {
+        "allowUnknownTags": false
+    },
+    "plugins": [
+        "./tsd-jsdoc/plugin"
+    ],
+    "opts": {
+        "encoding"      : "utf8",
+        "recurse"       : true,
+        "lenient"       : true,
+        "template"      : "./tsd-jsdoc",
+
+        "private"       : false,
+        "comments"      : true,
+        "destination"   : false
+    }
+}

package/cli/package.json

@@ -0,0 +1,7 @@
+{
+  "version": "6.7.0",
+  "dependencies": {
+    "jsdoc": "^3.6.3",
+    "minimist": "^1.2.0"
+  }
+}