build(aio): add new post-process dgeni package

This package will allow us to do complex post-processing
on the HTML that is rendered by Nunjucks.

aio/tools/transforms/angular-base-package/index.js

@@ -14,11 +14,12 @@ const linksPackage = require('../links-package');
 const examplesPackage = require('../examples-package');
 const targetPackage = require('../target-package');
 const remarkPackage = require('../remark-package');
+const postProcessPackage = require('../post-process-package');
 
 const { PROJECT_ROOT, DOCS_OUTPUT_PATH, TEMPLATES_PATH, requireFolder } = require('../config');
 
 module.exports = new Package('angular-base', [
-  jsdocPackage, nunjucksPackage, linksPackage, examplesPackage, targetPackage, remarkPackage
+  jsdocPackage, nunjucksPackage, linksPackage, examplesPackage, targetPackage, remarkPackage, postProcessPackage
 ])
 
   // Register the processors

aio/tools/transforms/post-process-package/index.js

@@ -0,0 +1,5 @@
+var Package = require('dgeni').Package;
+var base = require('dgeni-packages/base');
+
+module.exports = new Package('post-process-package', [base])
+  .processor(require('./processors/post-process-html'));

aio/tools/transforms/post-process-package/processors/post-process-html.js

@@ -0,0 +1,37 @@
+const rehype = require('rehype');
+
+/**
+ * @dgProcessor postProcessHtml
+ *
+ * @description
+ * Use the rehype processing engine to manipulate the
+ * `renderedContent` HTML via rehype "plugins" that work with HTML ASTs (HASTs).
+ * See https://github.com/wooorm/rehype
+ *
+ * Each plugin is a factory function that will be called with the "rehype" engine as `this`.
+ * The factory should return a function that takes a HAST and returns a `boolean` or `undefined`.
+ * The HAST can be mutated by the this function.
+ * If `false` is returned then the processing stops with that plugin.
+ *
+ * @property docTypes {string[]} the `docTypes` of docs that should be post-processed
+ * @property plugins {Function[]} the rehype plugins that will modify the HAST.
+ *
+ */
+module.exports = function postProcessHtml() {
+  return {
+    $runAfter: ['docs-rendered'],
+    $runBefore: ['writing-files'],
+    docTypes: [],
+    plugins: [],
+    $process(docs) {
+      const engine = rehype()
+            .data('settings', { fragment: true });
+      this.plugins.forEach(plugin => engine.use(plugin));
+
+      docs
+        .filter(doc => this.docTypes.indexOf(doc.docType) !== -1)
+        .forEach(doc =>
+          doc.renderedContent = engine.processSync(doc.renderedContent).contents);
+    }
+  };
+};

aio/tools/transforms/post-process-package/processors/post-process-html.spec.js

@@ -0,0 +1,62 @@
+const testPackage = require('../../helpers/test-package');
+const Dgeni = require('dgeni');
+
+describe('postProcessHtml', function() {
+  let dgeni, injector, processor;
+
+  beforeEach(function() {
+    dgeni = new Dgeni([testPackage('post-process-package', true)]);
+    injector = dgeni.configureInjector();
+    processor = injector.get('postProcessHtml');
+    processor.docTypes = ['a', 'b'];
+  });
+
+  it('should be available from the injector', () => {
+    expect(processor).toBeDefined();
+  });
+
+  it('should only process docs that match the specified docTypes', () => {
+    const elements = [];
+    const captureFirstElement = ast => {
+      elements.push(ast.children[0].tagName);
+    };
+    processor.plugins = [() => captureFirstElement];
+
+    const docs = [
+      { docType: 'a', renderedContent: '<a></a>' },
+      { docType: 'b', renderedContent: '<b></b>' },
+      { docType: 'c', renderedContent: '<c></c>' },
+      { docType: 'd', renderedContent: '<d></d>' },
+    ];
+    processor.$process(docs);
+    expect(elements).toEqual(['a', 'b']);
+  });
+
+  it('should run all the plugins on each doc', () => {
+    const capitalizeFirstElement = ast => {
+      ast.children[0].tagName = ast.children[0].tagName.toUpperCase();
+    };
+    const addOneToFirstElement = ast => {
+      ast.children[0].tagName = ast.children[0].tagName + '1';
+    };
+    const elements = [];
+    const captureFirstElement = ast => {
+      elements.push(ast.children[0].tagName);
+    };
+
+    const docs = [
+      { docType: 'a', renderedContent: '<a></a>' },
+      { docType: 'b', renderedContent: '<b></b>' },
+      { docType: 'c', renderedContent: '<c></c>' },
+      { docType: 'd', renderedContent: '<d></d>' },
+    ];
+
+    processor.plugins = [
+      () => capitalizeFirstElement,
+      () => addOneToFirstElement,
+      () => captureFirstElement
+    ];
+    processor.$process(docs);
+    expect(elements).toEqual(['A1', 'B1']);
+  });
+});