Who knows what's up with this shit anymore

megadoc · Jul 2, 2016 · 4f057c1 · 4f057c1
1 parent cf23169
commit 4f057c1
Show file tree

Hide file tree

Showing 73 changed files with 926 additions and 506 deletions.
diff --git a/bin/lint-ui b/bin/lint-ui
@@ -23,7 +23,7 @@ if [ -z $PACKAGE ]; then
 fi
 
 if [ -z $PACKAGE ]; then
-  SOURCES=(packages/*/ui)
+  SOURCES=(ui packages/*/ui)
 elif [ -d "packages/${PACKAGE}" ]; then
   SOURCES=("packages/${PACKAGE}/ui")
 elif [ -d "packages/megadoc-plugin-${PACKAGE}" ]; then

diff --git a/lib/AssetUtils.js b/lib/AssetUtils.js
@@ -1,7 +1,6 @@
 var path = require('path');
 var fs = require('fs-extra');
 var glob = require('glob');
-var console = require('./Logger')('megadoc');
 var merge = require('lodash').merge;
 
 function pathJoin(basePath, fragments) {
@@ -76,18 +75,36 @@ module.exports = function AssetUtils(config) {
      * @param  {String|Buffer} contents
      *         The contents of the file.
      */
-    writeAsset: function(fileName, contents) {
+    writeAsset: function(fileName, contents, options) {
       var filePath = utils.getAssetPath(config.outputDir, fileName);
       var dirPath = path.dirname(filePath);
 
       if (fs.existsSync(filePath)) {
+        if (options && options.forceOverwrite) {
+          if (fs.statSync(filePath).isDirectory()) {
+            console.error(
+              "ERROR: you are attempting to overwrite a directory destination! " +
+              "This is most likely a configuration error, like using a rewrite " +
+              "condition."
+            );
+
+            return 'ERR_FILE_EXISTS';
+          }
+
+          console.info("Overwriting existing asset at '%s'...", filePath);
+
+          fs.removeSync(filePath);
+
+          return utils.writeAsset(fileName, contents, options);
+        }
+
         console.error(
           "ERROR: A file or directory already exists at this path - it is not",
           "possible to overwrite!",
           filePath
         );
 
-        return false;
+        return 'ERR_FILE_EXISTS';
       }
       else if (fs.existsSync(dirPath) && !fs.statSync(dirPath).isDirectory()) {
         console.error(
@@ -96,7 +113,7 @@ module.exports = function AssetUtils(config) {
           dirPath, filePath
         );
 
-        return false;
+        return 'ERR_NOT_WRITABLE';
       }
 
       fs.ensureDirSync(dirPath);

diff --git a/lib/HTMLSerializer.js b/lib/HTMLSerializer.js
@@ -76,7 +76,7 @@ module.exports = function HTMLSerializer(config) {
           title: config.title,
           summary: config.metaDescription,
           meta: {
-            href: '/index'
+            href: '/index.html'
           },
         }),
 
@@ -85,7 +85,7 @@ module.exports = function HTMLSerializer(config) {
           title: '404 - Not Found',
           summary: 'Not Found',
           meta: {
-            href: '/404'
+            href: '/404.html'
           },
         }),
       ]

diff --git a/lib/HTMLSerializer__CorpusVisitor.js b/lib/HTMLSerializer__CorpusVisitor.js
@@ -15,23 +15,45 @@ module.exports = function(config) {
     DocumentEntity: decorateNode,
   };
 
+  // This will decorate a node with the following meta properties:
+  //
+  // @property {String} meta.href
+  //
+  // A fully-qualified URL to the document. This will include the file extension
+  // if applicable (multi-page-mode) and the hash segment if it's an entity.
+  //
+  // @property {String} meta.anchor
+  //
+  // A local URL (hash segment) that can be used to "jump" (anchor) to the
+  // document or the entity. In SPM (HashLocation) this is unused.
+  //
+  // @property {Boolean} meta.hrefRewritten
+  //
+  // Whether the href was not generated and instead an explicit rewritten URL
+  // was used. We need this so that we can force the generation of the .html
+  // file over any existing one (in case the rewrite shadows another document)
+  // and in the UI to accommodate for links to rewritten URLs.
+  //
   function decorateNode(node) {
     var href;
 
     // allow rewrite by filepath
-    if (node.filePath && rewriteMap[node.filePath]) {
+    if (node.filePath && rewriteMap.hasOwnProperty(node.filePath)) {
       href = rewriteMap[node.filePath];
+      node.meta.hrefRewritten = true;
     }
     // allow rewrite by UID
-    else if (rewriteMap[node.uid]) {
+    else if (rewriteMap.hasOwnProperty(node.uid)) {
       href = rewriteMap[node.uid];
+      node.meta.hrefRewritten = true;
     }
     else {
       href = g.NodeURI(node);
 
       // allow rewrite by URL
-      if (rewriteMap[href]) {
+      if (rewriteMap.hasOwnProperty(href)) {
         href = rewriteMap[href];
+        node.meta.hrefRewritten = true;
       }
     }
 

diff --git a/lib/HTMLSerializer__emitFiles.js b/lib/HTMLSerializer__emitFiles.js
@@ -137,7 +137,13 @@ function DocumentFileEmitter(params) {
         distanceFromRoot: distanceFromRoot
       });
 
-      compiler.utils.writeAsset(filePath, docHTML);
+      var rc = compiler.utils.writeAsset(filePath, docHTML, {
+        forceOverwrite: node.meta.hrefRewritten
+      });
+
+      if (rc === 'ERR_FILE_EXISTS') {
+        console.error('Offending document:', node.uid);
+      }
 
       done();
     });

diff --git a/lib/config.js b/lib/config.js
@@ -292,7 +292,58 @@ module.exports = {
      */
     aliases: {
       'shell': 'bash'
-    }
+    },
+
+    /**
+     * @property {Array.<Config~Template>}
+     *
+     * @typedef {Config~Template}
+     *
+     * A layout override configuration object. This object describes how to render
+     * a certain page. By default, megadoc will compute a preferred layout based on
+     * the type of document that is being rendered.
+     *
+     * @property {!Object} match
+     *           The parameters that control when this configuration applies.
+     *
+     * @property {("url"|"uid"|"type"|"namespace")} match.by
+     *           What we should match on.
+     *
+     * @property {String} match.on
+     *           The value for matching:
+     *
+     *           - If `match.by` was set to `url`, this would be the URL(s) of the
+     *           pages.
+     *           - If `match.by` was set to `uid`, this would be the corpus UIDs
+     *           of the documents.
+     *           - If `match.by` was set to `type`, this would be the corpus ADT
+     *           node type. See [[T]].
+     *
+     * @property {?String} using
+     * @property {Array.<Config~TemplateRegion>} regions
+     *
+     * @typedef {Config~TemplateRegion}
+     *
+     * A configuration object for a specific layout region.
+     *
+     * @property {!String} name
+     *           The name of the region. See [[Layout]] for the regions it defines.
+     *
+     * @property {?Object} options
+     *           Options to customize how the region looks like. Refer to each
+     *           region's documentation to know what options it supports.
+     *
+     * @property {Array.<Config~TemplateRegionOutlet>} outlets
+     *           The outlets to fill the region with.
+     *
+     * @typedef {Config~TemplateRegionOutlet}
+     *
+     * @property {!String} name
+     * @property {?Object} options
+     * @property {?String} using
+     * @property {?("cascade"|"fix")} [injectionStrategy="cascade"]
+     */
+    customLayouts: null
   },
 
   linkResolver: {

diff --git a/packages/megadoc-corpus/lib/CorpusIntegrityEnforcements.js b/packages/megadoc-corpus/lib/CorpusIntegrityEnforcements.js
@@ -1,9 +1,9 @@
-exports.apply = function(node) {
-  if (node.filePath) {
-    node.filePath = ensureLeadingSlash(node.filePath);
-  }
+exports.apply = function(/*node*/) {
+  // if (node.filePath) {
+  //   node.filePath = ensureLeadingSlash(node.filePath);
+  // }
 };
 
-function ensureLeadingSlash(x) {
-  return x[0] === '/' ? x : '/' + x;
-}
+// function ensureLeadingSlash(x) {
+//   return x[0] === '/' ? x : '/' + x;
+// }
diff --git a/packages/megadoc-corpus/lib/__tests__/CorpusIntegrityEnforcements.test.js b/packages/megadoc-corpus/lib/__tests__/CorpusIntegrityEnforcements.test.js
@@ -4,7 +4,7 @@ var assert = require('chai').assert;
 var Corpus = require("../Corpus");
 var b = require('../CorpusTypes').builders;
 
-describe('Corpus::IntegrityEnforcements', function() {
+describe.skip('Corpus::IntegrityEnforcements', function() {
   var corpus;
 
   beforeEach(function() {

diff --git a/packages/megadoc-plugin-git/lib/index.js b/packages/megadoc-plugin-git/lib/index.js
@@ -68,7 +68,10 @@ function createGitPlugin(userConfig) {
       compiler.corpus.visit({
         Document: function(node) {
           if (node.filePath) {
-            var filePath = path.join(compiler.config.assetRoot, node.filePath.replace(/^\//, ''));
+            var filePath = node.filePath[0] === '/' ?
+              node.filePath :
+              path.join(compiler.config.assetRoot, node.filePath)
+            ;
 
             if (!files[filePath]) {
               files[filePath] = [];

diff --git a/packages/megadoc-plugin-git/ui/outlets/StatsOutlet.js b/packages/megadoc-plugin-git/ui/outlets/StatsOutlet.js
@@ -10,7 +10,7 @@ const StatsOutlet = React.createClass({
   render() {
     const { documentNode } = this.props;
 
-    if (!documentNode.meta.gitStats) {
+    if (!documentNode || !documentNode.meta.gitStats) {
       return null;
     }
 
@@ -29,7 +29,7 @@ megadoc.outlets.add('Layout::Content', {
   key: 'Git::Stats',
   component: StatsOutlet,
   match(props) {
-    return !!props.documentNode.meta.gitStats;
+    return props.documentNode && !!props.documentNode.meta.gitStats;
   }
 });
 

diff --git a/packages/megadoc-plugin-js/lib/defaultLayouts.js b/packages/megadoc-plugin-js/lib/defaultLayouts.js
@@ -1,40 +1,40 @@
 module.exports = [];
 module.exports.push({
-  match: { by: 'type', on: 'Namespace' },
+  match: { by: 'type', on: [ 'Document', 'DocumentEntity' ] },
   regions: [
-    {
-      name: 'Layout::Sidebar',
-      outlets: [{ name: 'CJS::ClassBrowser' }]
-    },
-
     {
       name: 'Layout::Content',
       options: { framed: true },
       outlets: [
         { name: 'CJS::ModuleHeader' },
-        { name: 'CJS::NamespaceIndex' },
+        { name: 'CJS::ModuleIndex' },
+        { name: 'CJS::ModuleBody' },
         { name: 'Layout::Content' },
       ]
+    },
+    {
+      name: 'Layout::Sidebar',
+      outlets: [{ name: 'CJS::ClassBrowser' }]
     }
   ]
 });
 
 module.exports.push({
-  match: { by: 'type', on: [ 'Document', 'DocumentEntity' ] },
+  match: { by: 'type', on: 'Namespace' },
   regions: [
+    {
+      name: 'Layout::Sidebar',
+      outlets: [{ name: 'CJS::ClassBrowser' }]
+    },
+
     {
       name: 'Layout::Content',
       options: { framed: true },
       outlets: [
         { name: 'CJS::ModuleHeader' },
-        { name: 'CJS::ModuleIndex' },
-        { name: 'CJS::ModuleBody' },
+        { name: 'CJS::NamespaceIndex' },
         { name: 'Layout::Content' },
       ]
-    },
-    {
-      name: 'Layout::Sidebar',
-      outlets: [{ name: 'CJS::ClassBrowser' }]
     }
   ]
 });
diff --git a/packages/megadoc-plugin-js/lib/index.js b/packages/megadoc-plugin-js/lib/index.js
@@ -96,7 +96,7 @@ function Plugin(userConfig) {
     },
 
     addNodeAnalyzer: function(analyzer) {
-      emitter.on('analyze-node', analyzer);
+      emitter.on('process-node', analyzer);
       // parserConfig.nodeAnalyzers.push(analyzer);
     },
 

diff --git a/packages/megadoc-plugin-js/lib/scan.js b/packages/megadoc-plugin-js/lib/scan.js
@@ -1,6 +1,5 @@
 var Parser = require('./Parser');
 var K = require('./Parser/constants');
-var DocUtils = require('./Parser/DocUtils');
 
 module.exports = function scan(params, done) {
   var database;

diff --git a/packages/megadoc-plugin-js/ui/components/ClassBrowser.js b/packages/megadoc-plugin-js/ui/components/ClassBrowser.js
@@ -105,7 +105,6 @@ var ClassBrowser = React.createClass({
 
     const hasSelfDocument = ns.id !== '__general__' && (
       ns.properties ||
-      megadoc.hasCustomLayoutForDocument(ns) ||
       config.linkToNamespacesInBrowser
     );
 
@@ -165,6 +164,10 @@ var ClassBrowser = React.createClass({
       return null;
     }
 
+    if (!documentNode.properties.tags) {
+      console.log('weird docNode:', documentNode);
+    }
+
     const entityDocuments = orderAwareSort.asNodes(documentNode, documentNode.entities, 'id');
 
     return (

diff --git a/packages/megadoc-plugin-js/ui/components/DocTags.js b/packages/megadoc-plugin-js/ui/components/DocTags.js
@@ -11,6 +11,7 @@ var { where } = require('lodash');
 const HANDLED_TAGS = [
   'constructor',
   'class',
+  'deprecated',
   'example',
   'param',
   'return',

diff --git a/packages/megadoc-plugin-js/ui/components/FunctionSignature.js b/packages/megadoc-plugin-js/ui/components/FunctionSignature.js
@@ -20,11 +20,11 @@ const FunctionSignature = React.createClass({
     const { withNames } = this.props;
     const html = this.props.doc.tags
       .filter(function(tag) {
-        return tag.type === 'param' && tag.typeInfo.name.indexOf('.') === -1;
+        return tag.type === 'param' && (tag.typeInfo.name || '?').indexOf('.') === -1;
       })
       .map(function(param) {
         if (withNames) {
-          return '<em>' + param.typeInfo.name + '</em>: ' + describeType(param.typeInfo.type);
+          return '<em>' + (param.typeInfo.name || '?') + '</em>: ' + describeType(param.typeInfo.type);
         }
         else {
           return describeType(param.typeInfo.type);

diff --git a/packages/megadoc-plugin-js/ui/components/Tags/ExampleTag.js b/packages/megadoc-plugin-js/ui/components/Tags/ExampleTag.js
@@ -15,7 +15,7 @@ const ExampleTag = React.createClass({
   },
 
   render() {
-    const { name, description } = this.props.typeInfo;
+    const { name, } = this.props.typeInfo;
 
     return (
       <div className="example-tag">

diff --git a/packages/megadoc-plugin-js/ui/components/__tests__/ClassBrowser.test.js b/packages/megadoc-plugin-js/ui/components/__tests__/ClassBrowser.test.js
@@ -8,6 +8,7 @@ const Link = require('components/Link');
 describe('JS::Components::ClassBrowser', function() {
   const suite = reactSuite(this, stubContext(Subject), {
     namespaceNode: {
+      config: {},
       documents: [
         {
           uid: 'Cache',