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/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>' };