jsduck 3.7.0 → 3.8.0

data/lib/jsduck/welcome.rb

@@ -1,4 +1,5 @@
 require 'jsduck/null_object'
+require 'jsduck/io'
 
 module JsDuck
 
@@ -14,7 +15,7 @@ module JsDuck
 
     # Parses welcome HTML file with content for welcome page.
     def initialize(filename)
-      @html = IO.read(filename)
+      @html = JsDuck::IO.read(filename)
     end
 
     # Returns the HTML

data/opt/comments-server-side/app.js

@@ -138,7 +138,7 @@ app.namespace('/auth', function(){
                     });
                 }
             } else {
-                res.send("You are already unsubscribed.")
+                res.send("You are already unsubscribed.");
             }
         });
     });
@@ -156,34 +156,56 @@ app.namespace('/auth/:sdk/:version', function(){
      */
     app.get('/comments', function(req, res) {
 
+        if (!req.query.startkey) {
+            res.json({error: 'Invalid request'});
+            return;
+        }
+
         Comment.find({
             target: JSON.parse(req.query.startkey),
             deleted: { '$ne': true },
             sdk: req.params.sdk,
             version: req.params.version
         }).sort('createdAt', 1).run(function(err, comments){
-            res.json(util.formatComments(comments, req));
+            res.json(util.scoreComments(comments, req));
         });
     });
 
     /**
-     * Returns 100 most recent comments.
+     * Returns n most recent comments.
+     * Takes two parameters: offset and limit.
+     *
+     * The last comment object returned will contain `total_rows`,
+     * `offset` and `limit` fields. I'd say it's a hack, but at least
+     * it works for now.
      */
     app.get('/comments_recent', function(req, res) {
-        Comment.find({
+        var offset = parseInt(req.query.offset, 10) || 0;
+        var limit = parseInt(req.query.limit, 10) || 100;
+        var filter = {
             deleted: { '$ne': true },
             sdk: req.params.sdk,
             version: req.params.version
-        }).sort('createdAt', -1).limit(100).run(function(err, comments){
-            res.json(util.formatComments(comments, req));
+        };
+        Comment.find(filter).sort('createdAt', -1).skip(offset).limit(limit).run(function(err, comments) {
+            comments = util.scoreComments(comments, req);
+            // Count all comments, store count to last comment
+            Comment.count(filter).run(function(err, count) {
+                var last = comments[comments.length-1];
+                last.total_rows = count;
+                last.offset = offset;
+                last.limit = limit;
+                res.json(comments);
+            });
         });
     });
 
     /**
-     * Returns number of comments for each class / method
+     * Returns number of comments for each class/member,
+     * and a list of classes/members into which the user has subscribed.
      */
-    app.get('/comments_meta', util.getCommentsMeta, util.getCommentSubscriptions, function(req, res) {
-        res.send({ comments: req.commentsMeta, subscriptions: req.commentSubscriptions || [] });
+    app.get('/comments_meta', util.getCommentCounts, util.getCommentSubscriptions, function(req, res) {
+        res.send({ comments: req.commentCounts, subscriptions: req.commentSubscriptions || [] });
     });
 
     /**
@@ -210,7 +232,7 @@ app.namespace('/auth/:sdk/:version', function(){
             content: req.body.comment,
             action: req.body.action,
             rating: Number(req.body.rating),
-            contentHtml: util.sanitize(req.body.comment),
+            contentHtml: util.markdown(req.body.comment),
             downVotes: [],
             upVotes: [],
             createdAt: new Date,
@@ -241,24 +263,19 @@ app.namespace('/auth/:sdk/:version', function(){
         if (req.body.vote) {
             util.vote(req, res, comment);
         } else {
-            var canUpdate = _.include(req.session.user.membergroupids, 7) || req.session.user.username == comment.author;
-
-            if (!canUpdate) {
-                res.json({success: false, reason: 'Forbidden'}, 403);
-                return;
-            }
-
-            comment.content = req.body.content;
-            comment.contentHtml = util.sanitize(req.body.content);
-
-            comment.updates = comment.updates || [];
-            comment.updates.push({
-                updatedAt: String(new Date()),
-                author: req.session.user.username
-            });
+            util.requireOwner(req, res, function() {
+                comment.content = req.body.content;
+                comment.contentHtml = util.markdown(req.body.content);
+
+                comment.updates = comment.updates || [];
+                comment.updates.push({
+                    updatedAt: String(new Date()),
+                    author: req.session.user.username
+                });
 
-            comment.save(function(err, response) {
-                res.json({ success: true, content: comment.contentHtml });
+                comment.save(function(err, response) {
+                    res.json({ success: true, content: comment.contentHtml });
+                });
             });
         }
     });
@@ -266,25 +283,23 @@ app.namespace('/auth/:sdk/:version', function(){
     /**
      * Deletes a comment
      */
-    app.post('/comments/:commentId/delete', util.requireLoggedInUser, util.findComment, function(req, res) {
-
-        var canDelete = false,
-            comment = req.comment;
-
-        canDelete = _.include(req.session.user.membergroupids, 7) || req.session.user.username == req.comment.author;
-
-        if (!canDelete) {
-            res.json({ success: false, reason: 'Forbidden' }, 403);
-            return;
-        }
-
-        comment.deleted = true;
-
-        comment.save(function(err, response) {
+    app.post('/comments/:commentId/delete', util.requireLoggedInUser, util.findComment, util.requireOwner, function(req, res) {
+        req.comment.deleted = true;
+        req.comment.save(function(err, response) {
             res.send({ success: true });
         });
     });
 
+    /**
+     * Restores deleted comment
+     */
+    app.post('/comments/:commentId/undo_delete', util.requireLoggedInUser, util.findComment, util.requireOwner, function(req, res) {
+        req.comment.deleted = false;
+        req.comment.save(function(err, response) {
+            res.send({ success: true, comment: util.scoreComments([req.comment], req)[0] });
+        });
+    });
+
     /**
      * Get email subscriptions
      */
@@ -326,7 +341,7 @@ app.namespace('/auth/:sdk/:version', function(){
 
 });
 
-
-app.listen(3000);
-console.log("Server started...");
+var port = 3000;
+app.listen(port);
+console.log("Server started at port "+port+"...");
 

data/opt/comments-server-side/package.json

@@ -4,7 +4,7 @@
   "description": "Commenting backend for JSDuck Documentation",
   "author": "Nick Poudlen <nick@sencha.com>",
   "dependencies": {
-    "connect": "",
+    "connect": "1.8.5",
     "connect-session-mongo": "",
     "express": "",
     "express-namespace": "",

data/opt/comments-server-side/util.js

@@ -4,39 +4,41 @@ var marked = require('marked'),
     sanitizer = require('sanitizer'),
     nodemailer = require("nodemailer");
 
-exports.sanitize = function(content, opts) {
-
-    var markdowned, sanitized_output, urlFunc;
-
+/**
+ * Converts Markdown-formatted comment text into HTML.
+ *
+ * @param {String} content Markdown-formatted text
+ * @return {String} HTML
+ */
+exports.markdown = function(content) {
+    var markdowned;
     try {
         markdowned = marked(content);
     } catch(e) {
         markdowned = content;
     }
 
-    var exp = /(\bhttps?:\/\/[-A-Z0-9+&@#\/%?=~_|!:,.;]*[-A-Z0-9+&@#\/%=~_|])/igm;
-    markdowned = markdowned.replace(exp, "<a href='$1'>$1</a>");
-
-    if (opts && opts.stripUrls) {
-        urlFunc = function(str) {
-            if (str.match(/^(http:\/\/(www\.)?sencha.com|#))/)) {
-                return str;
-            } else {
-                return '';
-            }
-        };
-    }
-
-    sanitized_output = sanitizer.sanitize(markdowned, urlFunc);
-    sanitized_output = sanitized_output.replace(/&apos;/g, '&#39;');
+    // Strip dangerous markup, but allow links to all URL-s
+    var sanitized_output = sanitizer.sanitize(markdowned, function(str) {
+        return str;
+    });
 
-    return sanitized_output;
+    // IE does not support &apos;
+    return sanitized_output.replace(/&apos;/g, '&#39;');
 };
 
-exports.formatComments = function(comments, req) {
-
+/**
+ * Calculates up/down scores for each comment.
+ *
+ * Marks if the current user has already voted on the comment.
+ * Ensures createdAt timestamp is a string.
+ *
+ * @param {Object[]} comments
+ * @param {Object} req Containing username data
+ * @return {Object[]}
+ */
+exports.scoreComments = function(comments, req) {
     return _.map(comments, function(comment) {
-
         comment = _.extend(comment._doc, {
             score: comment.upVotes.length - comment.downVotes.length,
             createdAt: String(comment.createdAt)
@@ -51,39 +53,46 @@ exports.formatComments = function(comments, req) {
     });
 };
 
+/**
+ * Performs voting on comment.
+ *
+ * @param {Object} req The request object.
+ * @param {Object} res The response object where voting result is written.
+ * @param {Comment} comment The comment to vote on.
+ */
 exports.vote = function(req, res, comment) {
-
     var voteDirection;
+    var username = req.session.user.username;
 
-    if (req.session.user.username == comment.author) {
+    if (username == comment.author) {
 
         // Ignore votes from the author
         res.json({success: false, reason: 'You cannot vote on your own content'});
         return;
 
-    } else if (req.body.vote == 'up' && !_.include(comment.upVotes, req.session.user.username)) {
+    } else if (req.body.vote == 'up' && !_.include(comment.upVotes, username)) {
 
-        var voted = _.include(comment.downVotes, req.session.user.username);
+        var voted = _.include(comment.downVotes, username);
 
         comment.downVotes = _.reject(comment.downVotes, function(v) {
-            return v == req.session.user.username;
+            return v == username;
         });
 
         if (!voted) {
             voteDirection = 'up';
-            comment.upVotes.push(req.session.user.username);
+            comment.upVotes.push(username);
         }
-    } else if (req.body.vote == 'down' && !_.include(comment.downVotes, req.session.user.username)) {
+    } else if (req.body.vote == 'down' && !_.include(comment.downVotes, username)) {
 
-        var voted = _.include(comment.upVotes, req.session.user.username);
+        var voted = _.include(comment.upVotes, username);
 
         comment.upVotes = _.reject(comment.upVotes, function(v) {
-            return v == req.session.user.username;
+            return v == username;
         });
 
         if (!voted) {
             voteDirection = 'down';
-            comment.downVotes.push(req.session.user.username);
+            comment.downVotes.push(username);
         }
     }
 
@@ -96,9 +105,14 @@ exports.vote = function(req, res, comment) {
     });
 };
 
-
+/**
+ * Ensures that user is logged in.
+ *
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ */
 exports.requireLoggedInUser = function(req, res, next) {
-
     if (!req.session || !req.session.user) {
         res.json({success: false, reason: 'Forbidden'}, 403);
     } else {
@@ -106,8 +120,16 @@ exports.requireLoggedInUser = function(req, res, next) {
     }
 };
 
+/**
+ * Looks up comment by ID.
+ *
+ * Stores it into `req.comment`.
+ *
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ */
 exports.findComment = function(req, res, next) {
-
     if (req.params.commentId) {
         Comment.findById(req.params.commentId, function(err, comment) {
             req.comment = comment;
@@ -116,18 +138,41 @@ exports.findComment = function(req, res, next) {
     } else {
         res.json({success: false, reason: 'No such comment'});
     }
+};
 
+/**
+ * Ensures that user is allowed to modify/delete the comment,
+ * that is, he is the owner of the comment or a moderator.
+ *
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ */
+exports.requireOwner = function(req, res, next) {
+    var isModerator = _.include(req.session.user.membergroupids, 7);
+    var isAuthor = req.session.user.username == req.comment.author;
+
+    if (isModerator || isAuthor) {
+        next();
+    }
+    else {
+        res.json({ success: false, reason: 'Forbidden' }, 403);
+    }
 };
 
+/**
+ * Sends e-mail updates when comment is posted to a thread that has
+ * subscribers.
+ *
+ * @param {Comment} comment
+ */
 exports.sendEmailUpdates = function(comment) {
-
     var mailTransport = nodemailer.createTransport("SMTP",{
         host: 'localhost',
         port: 25
     });
 
     var sendSubscriptionEmail = function(emails) {
-
         var email = emails.shift();
 
         if (email) {
@@ -143,7 +188,7 @@ exports.sendEmailUpdates = function(comment) {
              console.log("Finished sending emails");
              mailTransport.close();
         }
-    }
+    };
 
     var subscriptionBody = {
         sdk: comment.sdk,
@@ -154,7 +199,6 @@ exports.sendEmailUpdates = function(comment) {
     var emails = [];
 
     Subscription.find(subscriptionBody, function(err, subscriptions) {
-
         _.each(subscriptions, function(subscription) {
             var mailOptions = {
                 transport: mailTransport,
@@ -169,7 +213,7 @@ exports.sendEmailUpdates = function(comment) {
                     "Unsubscribe from this thread: http://projects.sencha.com/auth/unsubscribe/" + subscription._id,
                     "Unsubscribe from all threads: http://projects.sencha.com/auth/unsubscribe/" + subscription._id + '?all=true'
                 ].join("\n")
-            }
+            };
 
             if (Number(comment.userId) != Number(subscription.userId)) {
                 emails.push(mailOptions);
@@ -182,28 +226,43 @@ exports.sendEmailUpdates = function(comment) {
             console.log("No emails to send");
         }
     });
-}
-
-
-exports.getCommentsMeta = function(req, res, next) {
+};
 
+/**
+ * Retrieves comment counts for each target.
+ *
+ * Stores into `req.commentCounts` field an array like this:
+ *
+ *     [
+ *         {"_id": "class__Ext__", "value": 3},
+ *         {"_id": "class__Ext__method-define", "value": 1},
+ *         {"_id": "class__Ext.Panel__cfg-title", "value": 8}
+ *     ]
+ *
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ */
+exports.getCommentCounts = function(req, res, next) {
+    // Map each comment into: ("type__Class__member", 1)
     var map = function() {
         if (this.target) {
             emit(this.target.slice(0,3).join('__'), 1);
         } else {
             return;
         }
-    }
+    };
 
+    // Sum comment counts for each target
     var reduce = function(key, values) {
-        var i = 0, total = 0;
+        var total = 0;
 
-        for (; i< values.length; i++) {
+        for (var i = 0; i < values.length; i++) {
             total += values[i];
         }
 
         return total;
-    }
+    };
 
     mongoose.connection.db.executeDbCommand({
         mapreduce: 'comments',
@@ -218,13 +277,29 @@ exports.getCommentsMeta = function(req, res, next) {
     }, function(err, dbres) {
         mongoose.connection.db.collection('commentCounts', function(err, collection) {
             collection.find({}).toArray(function(err, comments) {
-                req.commentsMeta = comments;
-                next()
+                req.commentCounts = comments;
+                next();
             });
         });
     });
-}
+};
 
+/**
+ * Retrieves list of commenting targets into which the current user
+ * has subscribed for e-mail updates.
+ *
+ * Stores them into `req.commentSubscriptions` field as array:
+ *
+ *     [
+ *         ["class", "Ext", ""],
+ *         ["class", "Ext", "method-define"],
+ *         ["class", "Ext.Panel", "cfg-title"]
+ *     ]
+ *
+ * @param {Object} req
+ * @param {Object} res
+ * @param {Function} next
+ */
 exports.getCommentSubscriptions = function(req, res, next) {
     if (req.session.user) {
         Subscription.find({
@@ -236,10 +311,10 @@ exports.getCommentSubscriptions = function(req, res, next) {
                 return subscription.target;
             });
             next();
-        })
+        });
     } else {
         next();
     }
-}
+};