build(aio): tighten up code autolinking (#20468)

Do not match code "words" that are part of a hyphenated
string of characters: e.g. `platform-browser-dynamic` should
not auto-link `browser`.

Do not match code "words" that correspond to pipe names
but are not preceded by a pipe `|` character. E.g. `package.json` should
not auto link `json` to the `JsonPipe`.

Closes #20187

PR Close #20468

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

@@ -35,6 +35,7 @@ module.exports = new Package('angular-base', [
   .factory('packageInfo', function() { return require(path.resolve(PROJECT_ROOT, 'package.json')); })
   .factory(require('./readers/json'))
   .factory(require('./services/copyFolder'))
+  .factory(require('./services/filterPipes'))
   .factory(require('./services/getImageDimensions'))
 
   .factory(require('./post-processors/add-image-dimensions'))
@@ -126,8 +127,9 @@ module.exports = new Package('angular-base', [
   })
 
 
-  .config(function(postProcessHtml, addImageDimensions, autoLinkCode) {
+  .config(function(postProcessHtml, addImageDimensions, autoLinkCode, filterPipes) {
     addImageDimensions.basePath = path.resolve(AIO_PATH, 'src');
+    autoLinkCode.customFilters = [filterPipes];
     postProcessHtml.plugins = [
       require('./post-processors/autolink-headings'),
       addImageDimensions,

aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js

@@ -10,12 +10,19 @@ const textContent = require('hast-util-to-string');
  * Only docs that have one of these docTypes will be linked to.
  * Usually set to the API exported docTypes, e.g. "class", "function", "directive", etc.
  *
+ * @property customFilters array of functions `(docs, words, wordIndex) => docs` that will filter
+ * out docs where a word should not link to a doc.
+ *   - `docs` is the array of docs that match the link `word`
+ *   - `words` is the collection of words parsed from the code text
+ *   - `wordIndex` is the index of the current `word` for which we are finding a link
+ *
  * @property codeElements an array of strings.
  * Only text contained in these elements will be linked to.
  * Usually set to "code" but also "code-example" for angular.io.
  */
 module.exports = function autoLinkCode(getDocFromAlias) {
   autoLinkCodeImpl.docTypes = [];
+  autoLinkCodeImpl.customFilters = [];
   autoLinkCodeImpl.codeElements = ['code'];
   return autoLinkCodeImpl;
 
@@ -38,12 +45,13 @@ module.exports = function autoLinkCode(getDocFromAlias) {
                 parent.children.splice(index, 1, createLinkNode(docs[0], node.value));
               } else {
                 // Parse the text for words that we can convert to links
-                const nodes = textContent(node).split(/([A-Za-z0-9_]+)/)
+                const nodes = textContent(node).split(/([A-Za-z0-9_-]+)/)
                   .filter(word => word.length)
-                  .map(word => {
-                    const docs = getDocFromAlias(word);
-                    return foundValidDoc(docs) ?
-                              createLinkNode(docs[0], word) : // Create a link wrapping the text node.
+                  .map((word, index, words) => {
+                    // remove docs that fail the custom filter tests
+                    const filteredDocs = autoLinkCodeImpl.customFilters.reduce((docs, filter) => filter(docs, words, index), getDocFromAlias(word));
+                    return foundValidDoc(filteredDocs) ?
+                              createLinkNode(filteredDocs[0], word) : // Create a link wrapping the text node.
                               { type: 'text', value: word };  // this is just text so push a new text node
                   });
 

aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js

@@ -2,7 +2,7 @@ var createTestPackage = require('../../helpers/test-package');
 var Dgeni = require('dgeni');
 
 describe('autoLinkCode post-processor', () => {
-  let processor, autoLinkCode, aliasMap;
+  let processor, autoLinkCode, aliasMap, filterPipes;
 
   beforeEach(() => {
     const testPackage = createTestPackage('angular-base-package');
@@ -14,6 +14,7 @@ describe('autoLinkCode post-processor', () => {
     processor = injector.get('postProcessHtml');
     processor.docTypes = ['test-doc'];
     processor.plugins = [autoLinkCode];
+    filterPipes = injector.get('filterPipes');
   });
 
   it('should insert an anchor into every code item that matches the id of an API doc', () => {
@@ -51,6 +52,26 @@ describe('autoLinkCode post-processor', () => {
     expect(doc.renderedContent).toEqual('<code>MyClass</code>');
   });
 
+  it('should ignore code items that match an API doc but are attached to other text via a dash', () => {
+    aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' });
+    const doc = { docType: 'test-doc', renderedContent: '<code>xyz-MyClass</code>' };
+    processor.$process([doc]);
+    expect(doc.renderedContent).toEqual('<code>xyz-MyClass</code>');
+  });
+
+  it('should ignore code items that are filtered out by custom filters', () => {
+    autoLinkCode.customFilters = [filterPipes];
+    aliasMap.addDoc({ docType: 'pipe', id: 'MyClass', aliases: ['MyClass', 'myClass'], path: 'a/b/myclass', pipeOptions: { name: '\'myClass\'' } });
+    const doc = { docType: 'test-doc', renderedContent: '<code>{ xyz | myClass } { xyz|myClass } MyClass myClass OtherClass|MyClass</code>' };
+    processor.$process([doc]);
+    expect(doc.renderedContent).toEqual('<code>' +
+                                        '{ xyz | <a href="a/b/myclass" class="code-anchor">myClass</a> } '  +
+                                        '{ xyz|<a href="a/b/myclass" class="code-anchor">myClass</a> } ' +
+                                        '<a href="a/b/myclass" class="code-anchor">MyClass</a> ' +
+                                        'myClass OtherClass|<a href="a/b/myclass" class="code-anchor">MyClass</a>' +
+                                        '</code>');
+  });
+
   it('should insert anchors for individual text nodes within a code block', () => {
     aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' });
     const doc = { docType: 'test-doc', renderedContent: '<code><span>MyClass</span><span>MyClass</span></code>' };

aio/tools/transforms/angular-base-package/services/filterPipes.js

@@ -0,0 +1,12 @@
+
+/**
+ * This service is used by the autoLinkCode post-processors to filter out pipe docs
+ * where the matching word is the pipe name and is not preceded by a pipe
+ */
+module.exports = function filterPipes() {
+  return (docs, words, index) =>
+    docs.filter(doc =>
+      doc.docType !== 'pipe' ||
+      doc.pipeOptions.name !== '\'' + words[index] + '\'' ||
+      index > 0 && words[index - 1].trim() === '|');
+};

aio/tools/transforms/angular-base-package/services/filterPipes.spec.js

@@ -0,0 +1,36 @@
+const filterPipes = require('./filterPipes')();
+
+describe('filterPipes', () => {
+  it('should ignore docs that are not pipes', () => {
+    const docs = [{ docType: 'class', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    const words = ['A', 'b', 'B', 'C'];
+    const filteredDocs = [{ docType: 'class', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    expect(filterPipes(docs, words, 1)).toEqual(filteredDocs);
+    expect(filterPipes(docs, words, 2)).toEqual(filteredDocs);
+  });
+
+  it('should ignore docs that are pipes but do not match the pipe name', () => {
+    const docs = [{ docType: 'pipe', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    const words = ['A', 'B', 'C'];
+    const filteredDocs = [{ docType: 'pipe', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    expect(filterPipes(docs, words, 1)).toEqual(filteredDocs);
+  });
+
+  it('should ignore docs that are pipes, match the pipe name and are preceded by a pipe character', () => {
+    const docs = [{ docType: 'pipe', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    const words = ['A', '|', 'b', 'C'];
+    const filteredDocs = [{ docType: 'pipe', name: 'B', pipeOptions: { name: '\'b\'' } }];
+    expect(filterPipes(docs, words, 2)).toEqual(filteredDocs);
+  });
+
+  it('should filter out docs that are pipes, match the pipe name but are not preceded by a pipe character', () => {
+    const docs = [
+      { docType: 'pipe', name: 'B', pipeOptions: { name: '\'b\'' } },
+      { docType: 'class', name: 'B' }
+    ];
+    const words = ['A', 'b', 'C'];
+    const index = 1;
+    const filteredDocs = [{ docType: 'class', name: 'B' }];
+    expect(filterPipes(docs, words, index)).toEqual(filteredDocs);
+  });
+});