Add ability to "Crossdartify" the source code

If there's a crossdart.json file in the input dir (which can be
generated by Crossdart), it will use that file to add links to
crossdart.info in the source code block.

Since now we should support links in the source code section, I removed
`<code>` wrapping tags from it, and also now I HTML escape the source
code, and use triple mustache curly braces (`{{{sourceCode}}}`) to
insert it to the page.

Hopefully, that will simplify developer's life, when they want to look
into the method's implementation.

Author: astashov

bin/dartdoc.dart

@@ -123,7 +123,10 @@ main(List<String> arguments) async {
   var addCrossdart = args['add-crossdart'] as bool;
   var includeSource = args['include-source'] as bool;
 
-  initializeConfig(addCrossdart: addCrossdart, includeSource: includeSource);
+  initializeConfig(
+      addCrossdart: addCrossdart,
+      includeSource: includeSource,
+      inputDir: inputDir);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
       outputDir, packageMeta, includeLibraries,

lib/resources/styles.css

@@ -178,6 +178,16 @@ h2 .crossdart {
   margin-top: 1em;
 }
 
+.crossdart-link {
+  border-bottom: 1px solid #dfdfdf;
+  text-decoration: none;
+}
+
+.crossdart-link:hover {
+  border-bottom: 1px solid #aaa;
+  text-decoration: none;
+}
+
 @media(max-width: 768px) {
   nav .container {
     width: 100%

lib/src/config.dart

@@ -1,14 +1,18 @@
 library dartdoc.config;
 
+import 'dart:io';
+
 class Config {
+  final Directory inputDir;
   final bool addCrossdart;
   final bool includeSource;
-  Config._(this.addCrossdart, this.includeSource);
+  Config._(this.inputDir, this.addCrossdart, this.includeSource);
 }
 
 Config _config;
 Config get config => _config;
 
-void initializeConfig({bool addCrossdart: false, bool includeSource: true}) {
-  _config = new Config._(addCrossdart, includeSource);
+void initializeConfig(
+    {Directory inputDir, bool addCrossdart: false, bool includeSource: true}) {
+  _config = new Config._(inputDir, addCrossdart, includeSource);
 }

lib/src/model.dart

@@ -1926,6 +1926,24 @@ class Parameter extends ModelElement implements EnclosedElement {
   String toString() => element.name;
 }
 
+Map<String, Map<String, List<Map<String, dynamic>>>> __crossdartJson;
+Map<String, Map<String, List<Map<String, dynamic>>>> get _crossdartJson {
+  if (__crossdartJson == null) {
+    if (config != null) {
+      var crossdartFile =
+          new File(p.join(config.inputDir.path, "crossdart.json"));
+      if (crossdartFile.existsSync()) {
+        __crossdartJson = JSON.decode(crossdartFile.readAsStringSync());
+      } else {
+        __crossdartJson = {};
+      }
+    } else {
+      __crossdartJson = {};
+    }
+  }
+  return __crossdartJson;
+}
+
 abstract class SourceCodeMixin {
   String _sourceCodeCache;
   String get crossdartHtmlTag {
@@ -1942,6 +1960,10 @@ abstract class SourceCodeMixin {
 
   Library get library;
 
+  void clearSourceCodeCache() {
+    _sourceCodeCache = null;
+  }
+
   String get sourceCode {
     if (_sourceCodeCache == null) {
       String contents = getFileContentsFor(element);
@@ -1958,8 +1980,14 @@ abstract class SourceCodeMixin {
         }
 
         // Trim the common indent from the source snippet.
-        String source =
-            contents.substring(node.offset - (node.offset - i), node.end);
+        var start = node.offset - (node.offset - i);
+        String source = contents.substring(start, node.end);
+
+        if (config != null && config.addCrossdart) {
+          source = crossdartifySource(_crossdartJson, source, element, start);
+        } else {
+          source = const HtmlEscape().convert(source);
+        }
         source = stripIndentFromSource(source);
         source = stripDartdocCommentsFromSource(source);
 
@@ -1976,14 +2004,18 @@ abstract class SourceCodeMixin {
     if (_lineNumber != null && _sourceFilePath != null) {
       String packageName = library.package.isSdk ? "sdk" : library.package.name;
       String packageVersion = library.package.version;
-      var root = "${library.package.packageMeta.resolvedDir}/lib"
-          .replaceAll("\\", "/");
-      var sourceFilePath = _sourceFilePath
+      var root = library.package.packageMeta.resolvedDir;
+      if (!library.package.isSdk) {
+        root += "/lib";
+      }
+      root = root.replaceAll("\\", "/");
+      var sourceFilePath = new File(_sourceFilePath)
+          .resolveSymbolicLinksSync()
           .replaceAll("\\", "/")
           .replaceAll(root, "")
           .replaceAll(new RegExp(r"^/*"), "");
       String url =
-          "//crossdart.info/p/$packageName/$packageVersion/$sourceFilePath.html";
+          "//www.crossdart.info/p/$packageName/$packageVersion/$sourceFilePath.html";
       return "${url}#line-${_lineNumber}";
     } else {
       return null;

lib/src/model_utils.dart

@@ -5,12 +5,15 @@
 library dartdoc.model_utils;
 
 import 'dart:io';
+import 'dart:convert';
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/sdk.dart';
 import 'package:analyzer/src/generated/source_io.dart';
+import 'package:path/path.dart' as p;
+import 'config.dart';
 
 final Map<String, String> _fileContents = <String, String>{};
 
@@ -79,20 +82,27 @@ bool isPublic(Element e) {
 /// Strip leading dartdoc comments from the given source code.
 String stripDartdocCommentsFromSource(String source) {
   String remainer = source.trimLeft();
-  bool lineComments = remainer.startsWith('///');
-  bool blockComments = remainer.startsWith('/**');
+  HtmlEscape sanitizer = const HtmlEscape();
+  bool lineComments = remainer.startsWith('///') ||
+      remainer.startsWith(sanitizer.convert('///'));
+  bool blockComments = remainer.startsWith('/**') ||
+      remainer.startsWith(sanitizer.convert('/**'));
 
   return source.split('\n').where((String line) {
     if (lineComments) {
-      if (line.startsWith('///')) return false;
+      if (line.startsWith('///') || line.startsWith(sanitizer.convert('///'))) {
+        return false;
+      }
       lineComments = false;
       return true;
     } else if (blockComments) {
-      if (line.contains('*/')) {
+      if (line.contains('*/') || line.contains(sanitizer.convert('*/'))) {
         blockComments = false;
         return false;
       }
-      if (line.startsWith('/**')) return false;
+      if (line.startsWith('/**') || line.startsWith(sanitizer.convert('/**'))) {
+        return false;
+      }
       return false;
     }
 
@@ -109,3 +119,45 @@ String stripIndentFromSource(String source) {
     return line.startsWith(indent) ? line.substring(indent.length) : line;
   }).join('\n');
 }
+
+/// Add links to crossdart.info to the given source fragment
+String crossdartifySource(
+    Map<String, Map<String, List<Map<String, dynamic>>>> json,
+    String source,
+    Element element,
+    int start) {
+  var sanitizer = const HtmlEscape();
+  String newSource;
+  if (json.isNotEmpty) {
+    var node = element.computeNode();
+    var file =
+        element.source.fullName.replaceAll("${config.inputDir.path}/", "");
+    var filesData = json[file];
+    if (filesData != null) {
+      var data = filesData["references"]
+          .where((r) => r["offset"] >= start && r["end"] <= node.end);
+      if (data.isNotEmpty) {
+        var previousStop = 0;
+        var stringBuffer = new StringBuffer();
+        for (var item in data) {
+          stringBuffer.write(sanitizer
+              .convert(source.substring(previousStop, item["offset"] - start)));
+          stringBuffer
+              .write("<a class='crossdart-link' href='${item["remotePath"]}'>");
+          stringBuffer.write(sanitizer.convert(
+              source.substring(item["offset"] - start, item["end"] - start)));
+          stringBuffer.write("</a>");
+          previousStop = item["end"] - start;
+        }
+        stringBuffer.write(
+            sanitizer.convert(source.substring(previousStop, source.length)));
+
+        newSource = stringBuffer.toString();
+      }
+    }
+  }
+  if (newSource == null) {
+    newSource = sanitizer.convert(source);
+  }
+  return newSource;
+}

lib/templates/_source_code.html

@@ -1,5 +1,5 @@
 {{#hasSourceCode}}
 <section class="summary source-code" id="source">
   <h2><span>Source</span> {{{crossdartHtmlTag}}}</h2>
-  <pre><code class="prettyprint lang-dart">{{ sourceCode }}</code></pre>
+  <pre class="prettyprint lang-dart">{{{ sourceCode }}}</pre>
 </section>{{/hasSourceCode}}

test/model_test.dart

@@ -12,6 +12,7 @@ import 'package:dartdoc/src/model.dart';
 import 'package:dartdoc/src/model_utils.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:test/test.dart';
+import 'package:path/path.dart' as p;
 
 import 'src/utils.dart' as utils;
 
@@ -805,6 +806,7 @@ void main() {
     });
 
     test('has source code', () {
+      initializeConfig(addCrossdart: false);
       expect(topLevelFunction.sourceCode, startsWith('@deprecated'));
       expect(topLevelFunction.sourceCode, endsWith('''
 String topLevelFunction(int param1, bool param2, Cool coolBeans,
@@ -844,6 +846,13 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .singleWhere((m) => m.name == 'convertToMap');
     });
 
+    tearDown(() {
+      var file = new File(p.join(Directory.current.path, "crossdart.json"));
+      if (file.existsSync()) {
+        file.deleteSync();
+      }
+    });
+
     test('has a fully qualified name', () {
       expect(m1.fullyQualifiedName, 'ex.B.m1');
     });
@@ -920,7 +929,22 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     });
 
     test('method source code indents correctly', () {
-      expect(convertToMap.sourceCode, 'Map<X, Y> convertToMap() => null;');
+      initializeConfig(addCrossdart: false);
+      expect(convertToMap.sourceCode,
+          'Map&lt;X, Y&gt; convertToMap() =&gt; null;');
+    });
+
+    test('method source code crossdartifies correctly', () {
+      convertToMap.clearSourceCodeCache();
+      new File(p.join(Directory.current.path, "crossdart.json"))
+          .writeAsStringSync("""
+              {"testing/test_package/lib/fake.dart":
+                {"references":[{"offset":5806,"end":5809,"remotePath":"http://www.example.com/fake.dart"}]}}
+      """);
+
+      initializeConfig(addCrossdart: true, inputDir: Directory.current);
+      expect(convertToMap.sourceCode,
+          "<a class='crossdart-link' href='http://www.example.com/fake.dart'>Map</a>&lt;X, Y&gt; convertToMap() =&gt; null;");
     });
 
     group(".crossdartHtmlTag()", () {
@@ -929,7 +953,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
         String packageName = m1.library.package.name;
         String packageVersion = m1.library.package.version;
         expect(m1.crossdartHtmlTag,
-            contains("//crossdart.info/p/$packageName/$packageVersion"));
+            contains("//www.crossdart.info/p/$packageName/$packageVersion"));
       });
 
       test('it returns an empty string when Crossdart support is disabled', () {