Merge head to NNBD

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.1.0-dev
+* Experimental feature: HTML output from markdown rendering, `{@tool}` and
+  `{@inject-html}` is sanitized when hidden option `--sanitize-html` is passed.
+
 ## 4.0.0
 * BREAKING CHANGE: Refactors to support NNBD and adapt to new analyzer 
   changes are technically semver breaking.   If you make extensive use of

dartdoc_options.yaml

@@ -1,4 +1,4 @@
 dartdoc:
   linkToSource:
     root: '.'
-    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v4.0.0/%f%#L%l%'
+    uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v4.1.0-dev/%f%#L%l%'

lib/src/dartdoc_options.dart

@@ -1269,6 +1269,8 @@ class DartdocOptionContext extends DartdocOptionContextBase
 
   bool get injectHtml => optionSet['injectHtml'].valueAt(context);
 
+  bool get sanitizeHtml => optionSet['sanitizeHtml'].valueAt(context);
+
   bool get excludeFooterVersion =>
       optionSet['excludeFooterVersion'].valueAt(context);
 
@@ -1418,6 +1420,10 @@ Future<List<DartdocOption>> createDartdocOptions(
     DartdocOptionArgOnly<bool>('injectHtml', false, resourceProvider,
         help: 'Allow the use of the {@inject-html} directive to inject raw '
             'HTML into dartdoc output.'),
+    DartdocOptionArgOnly<bool>('sanitizeHtml', false, resourceProvider,
+        hide: true,
+        help: 'Sanitize HTML generated from markdown, {@tool} and '
+            '{@inject-html} directives.'),
     DartdocOptionArgOnly<String>(
         'input', resourceProvider.pathContext.current, resourceProvider,
         optionIs: OptionKind.dir,

lib/src/generator/templates.runtime_renderers.dart

@@ -15304,6 +15304,7 @@ const _invisibleGetters = {
     'includeExternal',
     'includeSource',
     'injectHtml',
+    'sanitizeHtml',
     'excludeFooterVersion',
     'tools',
     'inputDir',

lib/src/model/documentation.dart

@@ -53,8 +53,9 @@ class Documentation {
     }
     _hasExtendedDocs = parseResult.hasExtendedDocs;
 
-    var renderResult =
-        _renderer.render(parseResult.nodes, processFullDocs: processFullDocs);
+    var renderResult = _renderer.render(parseResult.nodes,
+        processFullDocs: processFullDocs,
+        sanitizeHtml: _element.config.sanitizeHtml);
 
     if (processFullDocs) {
       _asHtml = renderResult.asHtml;

lib/src/render/documentation_renderer.dart

@@ -2,13 +2,16 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:html/parser.dart' show parse;
+import 'package:html/dom.dart' as dom;
+import 'package:html/parser.dart' show parseFragment;
+
 import 'package:markdown/markdown.dart' as md;
 
 abstract class DocumentationRenderer {
   DocumentationRenderResult render(
     List<md.Node> nodes, {
     required bool processFullDocs,
+    required bool sanitizeHtml,
   });
 }
 
@@ -19,16 +22,16 @@ class DocumentationRendererHtml implements DocumentationRenderer {
   DocumentationRenderResult render(
     List<md.Node> nodes, {
     required bool processFullDocs,
+    required bool sanitizeHtml,
   }) {
     if (nodes.isEmpty) {
       return DocumentationRenderResult.empty;
     }
+
     var rawHtml = md.HtmlRenderer().render(nodes);
-    var asHtmlDocument = parse(rawHtml);
-    for (var s in asHtmlDocument.querySelectorAll('script')) {
-      s.remove();
-    }
-    for (var pre in asHtmlDocument.querySelectorAll('pre')) {
+    var asHtmlFragment = parseFragment(rawHtml);
+
+    for (var pre in asHtmlFragment.querySelectorAll('pre')) {
       if (pre.children.length > 1 && pre.children.first.localName != 'code') {
         continue;
       }
@@ -43,15 +46,21 @@ class DocumentationRendererHtml implements DocumentationRenderer {
       // Assume the user intended Dart if there are no other classes present.
       if (!specifiesLanguage) pre.classes.add('language-dart');
     }
+
+    if (sanitizeHtml) {
+      _sanitize(asHtmlFragment);
+    }
+
     var asHtml = '';
 
     if (processFullDocs) {
       // `trim` fixes an issue with line ending differences between Mac and
       // Windows.
-      asHtml = (asHtmlDocument.body?.innerHtml ?? '').trim();
+      asHtml = asHtmlFragment.outerHtml.trim();
     }
-    var children = asHtmlDocument.body?.children ?? [];
-    var asOneLiner = children.isEmpty ? '' : children.first.innerHtml;
+    var asOneLiner = asHtmlFragment.children.isEmpty
+        ? ''
+        : asHtmlFragment.children.first.innerHtml;
 
     return DocumentationRenderResult(asHtml: asHtml, asOneLiner: asOneLiner);
   }
@@ -60,9 +69,259 @@ class DocumentationRendererHtml implements DocumentationRenderer {
 class DocumentationRenderResult {
   static const empty = DocumentationRenderResult(asHtml: '', asOneLiner: '');
 
-  final String /*?*/ asHtml;
+  final String asHtml;
   final String asOneLiner;
 
   const DocumentationRenderResult(
       {required this.asHtml, required this.asOneLiner});
 }
+
+bool _allowClassName(String className) =>
+    className == 'deprecated' || className.startsWith('language-');
+
+Iterable<String> _addLinkRel(String uri) {
+  final u = Uri.tryParse(uri);
+  if (u != null && u.host.isNotEmpty) {
+    // TODO(jonasfj): Consider allowing non-ugc links for trusted sites.
+    return ['ugc'];
+  }
+  return [];
+}
+
+void _sanitize(dom.Node node) {
+  if (node is dom.Element) {
+    final tagName = node.localName!.toUpperCase();
+    if (!_allowedElements.contains(tagName)) {
+      node.remove();
+      return;
+    }
+    node.attributes.removeWhere((k, v) {
+      final attrName = k.toString();
+      if (attrName == 'class') {
+        node.classes.removeWhere((cn) => !_allowClassName(cn));
+        return node.classes.isEmpty;
+      }
+      return !_isAttributeAllowed(tagName, attrName, v);
+    });
+    if (tagName == 'A') {
+      final href = node.attributes['href'];
+      if (href != null) {
+        final rels = _addLinkRel(href);
+        if (rels.isNotEmpty) {
+          node.attributes['rel'] = rels.join(' ');
+        }
+      }
+    }
+  }
+  if (node.hasChildNodes()) {
+    // doing it in reverse order, because we could otherwise skip one, when a
+    // node is removed...
+    for (var i = node.nodes.length - 1; i >= 0; i--) {
+      _sanitize(node.nodes[i]);
+    }
+  }
+}
+
+bool _isAttributeAllowed(String tagName, String attrName, String value) {
+  if (_alwaysAllowedAttributes.contains(attrName)) return true;
+
+  // Special validators for special attributes on special tags (href/src/cite)
+  final attributeValidators = _elementAttributeValidators[tagName];
+  if (attributeValidators == null) {
+    return false;
+  }
+
+  final validator = attributeValidators[attrName];
+  if (validator == null) {
+    return false;
+  }
+
+  return validator(value);
+}
+
+// Inspired by the set of HTML tags allowed in GFM.
+final _allowedElements = <String>{
+  'H1',
+  'H2',
+  'H3',
+  'H4',
+  'H5',
+  'H6',
+  'H7',
+  'H8',
+  'BR',
+  'B',
+  'I',
+  'STRONG',
+  'EM',
+  'A',
+  'PRE',
+  'CODE',
+  'IMG',
+  'TT',
+  'DIV',
+  'INS',
+  'DEL',
+  'SUP',
+  'SUB',
+  'P',
+  'OL',
+  'UL',
+  'TABLE',
+  'THEAD',
+  'TBODY',
+  'TFOOT',
+  'BLOCKQUOTE',
+  'DL',
+  'DT',
+  'DD',
+  'KBD',
+  'Q',
+  'SAMP',
+  'VAR',
+  'HR',
+  'RUBY',
+  'RT',
+  'RP',
+  'LI',
+  'TR',
+  'TD',
+  'TH',
+  'S',
+  'STRIKE',
+  'SUMMARY',
+  'DETAILS',
+  'CAPTION',
+  'FIGURE',
+  'FIGCAPTION',
+  'ABBR',
+  'BDO',
+  'CITE',
+  'DFN',
+  'MARK',
+  'SMALL',
+  'SPAN',
+  'TIME',
+  'WBR',
+};
+
+// Inspired by the set of HTML attributes allowed in GFM.
+final _alwaysAllowedAttributes = <String>{
+  'abbr',
+  'accept',
+  'accept-charset',
+  'accesskey',
+  'action',
+  'align',
+  'alt',
+  'aria-describedby',
+  'aria-hidden',
+  'aria-label',
+  'aria-labelledby',
+  'axis',
+  'border',
+  'cellpadding',
+  'cellspacing',
+  'char',
+  'charoff',
+  'charset',
+  'checked',
+  'clear',
+  'cols',
+  'colspan',
+  'color',
+  'compact',
+  'coords',
+  'datetime',
+  'dir',
+  'disabled',
+  'enctype',
+  'for',
+  'frame',
+  'headers',
+  'height',
+  'hreflang',
+  'hspace',
+  'ismap',
+  'label',
+  'lang',
+  'maxlength',
+  'media',
+  'method',
+  'multiple',
+  'name',
+  'nohref',
+  'noshade',
+  'nowrap',
+  'open',
+  'prompt',
+  'readonly',
+  'rel',
+  'rev',
+  'rows',
+  'rowspan',
+  'rules',
+  'scope',
+  'selected',
+  'shape',
+  'size',
+  'span',
+  'start',
+  'summary',
+  'tabindex',
+  'target',
+  'title',
+  'type',
+  'usemap',
+  'valign',
+  'value',
+  'vspace',
+  'width',
+  'itemprop',
+};
+
+bool _alwaysAllowed(String _) => true;
+
+bool _validLink(String url) {
+  try {
+    final uri = Uri.parse(url);
+    return uri.isScheme('https') ||
+        uri.isScheme('http') ||
+        uri.isScheme('mailto') ||
+        !uri.hasScheme;
+  } on FormatException {
+    return false;
+  }
+}
+
+bool _validUrl(String url) {
+  try {
+    final uri = Uri.parse(url);
+    return uri.isScheme('https') || uri.isScheme('http') || !uri.hasScheme;
+  } on FormatException {
+    return false;
+  }
+}
+
+final _citeAttributeValidator = <String, bool Function(String)>{
+  'cite': _validUrl,
+};
+
+final _elementAttributeValidators =
+    <String, Map<String, bool Function(String)>>{
+  'A': {
+    'href': _validLink,
+  },
+  'IMG': {
+    'src': _validUrl,
+    'longdesc': _validUrl,
+  },
+  'DIV': {
+    'itemscope': _alwaysAllowed,
+    'itemtype': _alwaysAllowed,
+  },
+  'BLOCKQUOTE': _citeAttributeValidator,
+  'DEL': _citeAttributeValidator,
+  'INS': _citeAttributeValidator,
+  'Q': _citeAttributeValidator,
+};

lib/src/version.dart

@@ -1,2 +1,2 @@
 // Generated code. Do not modify.
-const packageVersion = '4.0.0';
+const packageVersion = '4.1.0-dev';

pubspec.yaml

@@ -1,6 +1,6 @@
 name: dartdoc
-# Run `grind build` after updating.
-version: 4.0.0
+# Run `dart run grinder build` after updating.
+version: 4.1.0-dev
 description: A non-interactive HTML documentation generator for Dart source code.
 homepage: https://github.com/dart-lang/dartdoc
 environment: