Add the --inject-html command line flag to enable HTML injection.

Author: gspencergoog

README.md

@@ -308,6 +308,9 @@ into the dartdoc output, without it being subject to Markdown processing
 beforehand. This can be useful when the output of an external tool is HTML, for
 instance. This is where the `{@inject-html}...{@end-inject-html}` tags come in.
 
+For security reasons, the `{@inject-html}` directive will be ignored unless the
+`--inject-html` flag is given on the dartdoc command line.
+
 Since this HTML fragment doesn't undergo Markdown processing, reference links
 and other normal processing won't happen on the contained fragment.
 

lib/src/dartdoc_options.dart

@@ -1140,6 +1140,7 @@ class DartdocOptionContext {
   List<String> get includeExternal =>
       optionSet['includeExternal'].valueAt(context);
   bool get includeSource => optionSet['includeSource'].valueAt(context);
+  bool get injectHtml => optionSet['injectHtml'].valueAt(context);
   ToolConfiguration get tools => optionSet['tools'].valueAt(context);
 
   /// _input is only used to construct synthetic options.
@@ -1254,6 +1255,8 @@ Future<List<DartdocOption>> createDartdocOptions() async {
         splitCommas: true),
     new DartdocOptionArgOnly<bool>('includeSource', true,
         help: 'Show source code blocks.', negatable: true),
+    new DartdocOptionArgOnly<bool>('injectHtml', false,
+        help: 'Allow the use of {@inject-html} directive to inject raw HTML.'),
     new DartdocOptionArgOnly<String>('input', Directory.current.path,
         isDir: true, help: 'Path to source directory', mustExist: true),
     new DartdocOptionSyntheticOnly<String>('inputDir',

lib/src/model.dart

@@ -4089,6 +4089,7 @@ abstract class ModelElement extends Canonicalization
   /// And the HTML fragment will not have been processed or changed by Markdown,
   /// but just injected verbatim.
   String _injectHtmlFragments(String rawDocs) {
+    if (!config.injectHtml) return rawDocs;
     final macroRegExp = new RegExp(r'<dartdoc-html>([a-f0-9]+)</dartdoc-html>');
     return rawDocs.replaceAllMapped(macroRegExp, (match) {
       String fragment = packageGraph.getHtmlFragment(match[1]);
@@ -4167,6 +4168,7 @@ abstract class ModelElement extends Canonicalization
   ///     &#123;@end-inject-html&#125;
   ///
   String _stripHtmlAndAddToIndex(String rawDocs) {
+    if (!config.injectHtml) return rawDocs;
     final templateRegExp = new RegExp(
         r'[ ]*{@inject-html\s*}([\s\S]+?){@end-inject-html}[ ]*\n?',
         multiLine: true);

test/model_test.dart

@@ -116,25 +116,62 @@ void main() {
     });
   });
 
-  group('HTML Injection', () {
+  group('HTML Injection when allowed', () {
     Class htmlInjection;
     Method injectSimpleHtml;
 
-    setUp(() {
-      htmlInjection = exLibrary.classes.firstWhere((c) => c.name == 'HtmlInjection');
-      injectSimpleHtml =
-          htmlInjection.allInstanceMethods.firstWhere((m) => m.name == 'injectSimpleHtml');
-      packageGraph.allLocalModelElements.forEach((m) => m.documentation);
+    PackageGraph injectionPackageGraph;
+    Library injectionExLibrary;
+
+    setUpAll(() async {
+      injectionPackageGraph = await utils.bootBasicPackage(
+          'testing/test_package', ['css', 'code_in_comments', 'excluded'],
+          additionalArguments: ['--inject-html']);
+
+      injectionExLibrary =
+          injectionPackageGraph.libraries.firstWhere((lib) => lib.name == 'ex');
+
+      htmlInjection = injectionExLibrary.classes
+          .firstWhere((c) => c.name == 'HtmlInjection');
+      injectSimpleHtml = htmlInjection.allInstanceMethods
+          .firstWhere((m) => m.name == 'injectSimpleHtml');
+      injectionPackageGraph.allLocalModelElements
+          .forEach((m) => m.documentation);
     });
+
     test("can inject HTML", () {
       expect(
           injectSimpleHtml.documentation,
-          contains('\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n'));
+          contains(
+              '\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n'));
+      expect(injectSimpleHtml.documentation,
+          isNot(contains('\n{@inject-html}\n')));
       expect(injectSimpleHtml.documentationAsHtml,
           contains('   <div style="opacity: 0.5;">[HtmlInjection]</div>'));
     });
   });
 
+  group('HTML Injection when not allowed', () {
+    Class htmlInjection;
+    Method injectSimpleHtml;
+
+    setUp(() {
+      htmlInjection =
+          exLibrary.classes.firstWhere((c) => c.name == 'HtmlInjection');
+      injectSimpleHtml = htmlInjection.allInstanceMethods
+          .firstWhere((m) => m.name == 'injectSimpleHtml');
+      packageGraph.allLocalModelElements.forEach((m) => m.documentation);
+    });
+    test("doesn't inject HTML if --inject-html option is not present", () {
+      expect(
+          injectSimpleHtml.documentation,
+          isNot(contains(
+              '\n<dartdoc-html>bad2bbdd4a5cf9efb3212afff4449904756851aa</dartdoc-html>\n')));
+      expect(injectSimpleHtml.documentation, isNot(contains('<dartdoc-html>')));
+      expect(injectSimpleHtml.documentationAsHtml, contains('{@inject-html}'));
+    });
+  });
+
   group('Missing and Remote', () {
     test('Verify that SDK libraries are not canonical when missing', () {
       expect(
@@ -1995,8 +2032,9 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           reason: "Can't find convertToMap function in ${fakePath}");
       if (Platform.isWindows) fakePath = fakePath.replaceAll('/', r'\\');
 
-      crossdartPackageGraph = await utils
-          .bootBasicPackage(utils.testPackageDir.path, [], withCrossdart: true);
+      crossdartPackageGraph = await utils.bootBasicPackage(
+          utils.testPackageDir.path, [],
+          additionalArguments: ['--add-crossdart']);
       crossdartFakeLibrary =
           crossdartPackageGraph.libraries.firstWhere((l) => l.name == 'fake');
       HasGenerics = crossdartFakeLibrary.classes

test/src/utils.dart

@@ -60,18 +60,22 @@ void delete(Directory dir) {
   if (dir.existsSync()) dir.deleteSync(recursive: true);
 }
 
-void init() async {
+void init({List<String> additionalArguments}) async {
   sdkDir = defaultSdkDir;
   sdkPackageMeta = new PackageMeta.fromDir(sdkDir);
+  additionalArguments ??= <String>[];
 
   testPackageGraph = await bootBasicPackage(
-      'testing/test_package', ['css', 'code_in_comments', 'excluded']);
+      'testing/test_package', ['css', 'code_in_comments', 'excluded'],
+      additionalArguments: additionalArguments);
   testPackageGraphGinormous = await bootBasicPackage(
       'testing/test_package', ['css', 'code_in_commnets', 'excluded'],
-      withAutoIncludedDependencies: true);
+      additionalArguments:
+          additionalArguments + ['--auto-include-dependencies']);
 
-  testPackageGraphSmall =
-      await bootBasicPackage('testing/test_package_small', []);
+  testPackageGraphSmall = await bootBasicPackage(
+      'testing/test_package_small', [],
+      additionalArguments: additionalArguments);
   testPackageGraphSdk = await bootSdkPackage();
 }
 
@@ -82,18 +86,17 @@ Future<PackageGraph> bootSdkPackage() async {
 
 Future<PackageGraph> bootBasicPackage(
     String dirPath, List<String> excludeLibraries,
-    {bool withAutoIncludedDependencies = false,
-    bool withCrossdart = false}) async {
+    {List<String> additionalArguments}) async {
   Directory dir = new Directory(dirPath);
+  additionalArguments ??= <String>[];
   return new PackageBuilder(await contextFromArgv([
-    '--input',
-    dir.path,
-    '--sdk-dir',
-    sdkDir.path,
-    '--exclude',
-    excludeLibraries.join(','),
-    '--${withCrossdart ? "" : "no-"}add-crossdart',
-    '--${withAutoIncludedDependencies ? "" : "no-"}auto-include-dependencies'
-  ]))
+            '--input',
+            dir.path,
+            '--sdk-dir',
+            sdkDir.path,
+            '--exclude',
+            excludeLibraries.join(','),
+          ] +
+          additionalArguments))
       .buildPackageGraph();
 }

testing/test_package_docs/ex/HtmlInjection-class.html

@@ -159,7 +159,8 @@ <h2>Methods</h2>
           </span>
           </dt>
         <dd>
-          Injects some HTML. <a href="ex/HtmlInjection/injectSimpleHtml.html">[...]</a>
+          Injects some HTML.
+{@inject-html} <a href="ex/HtmlInjection/injectSimpleHtml.html">[...]</a>
 
 </dd>
         <dt id="noSuchMethod" class="callable inherited">

testing/test_package_docs/ex/HtmlInjection/injectSimpleHtml.html

@@ -70,10 +70,9 @@ <h1>injectSimpleHtml method</h1>
 (<wbr>)
     </section>
     <section class="desc markdown">
-      <p>Injects some HTML.</p>
-<p>
-   <div style="opacity: 0.5;">[HtmlInjection]</div>
-</p>
+      <p>Injects some HTML.
+{@inject-html}</p>   <div style="opacity: 0.5;">[HtmlInjection]</div>
+{@end-inject-html}
     </section>
 
 

testing/test_package_docs_dev/ex/HtmlInjection-class.html

@@ -159,7 +159,8 @@ <h2>Methods</h2>
           </span>
           </dt>
         <dd>
-          Injects some HTML. <a href="ex/HtmlInjection/injectSimpleHtml.html">[...]</a>
+          Injects some HTML.
+{@inject-html} <a href="ex/HtmlInjection/injectSimpleHtml.html">[...]</a>
 
 </dd>
         <dt id="noSuchMethod" class="callable inherited">

testing/test_package_docs_dev/ex/HtmlInjection/injectSimpleHtml.html

@@ -70,10 +70,9 @@ <h1>injectSimpleHtml method</h1>
 (<wbr>)
     </section>
     <section class="desc markdown">
-      <p>Injects some HTML.</p>
-<p>
-   <div style="opacity: 0.5;">[HtmlInjection]</div>
-</p>
+      <p>Injects some HTML.
+{@inject-html}</p>   <div style="opacity: 0.5;">[HtmlInjection]</div>
+{@end-inject-html}
     </section>