Add buildUrl option for GH enterprise, custom URLs

Reviewed-by: Titus Wormer <[email protected]>

Closes GH-23.
Closes GH-31.

Author: EvHaus

index.js

@@ -1,8 +1,52 @@
 /**
  * @typedef {import('mdast').Root} Root
  *
+ * @callback DefaultBuildUrl
+ * @param {BuildUrlValues} values
+ * @returns {string}
+ *
+ * @callback BuildUrl
+ * @param {BuildUrlValues} values
+ * @param {DefaultBuildUrl} defaultBuildUrl
+ * @returns {string}
+ *
+ * @typedef {BuildUrlCommitValues|BuildUrlCompareValues|BuildUrlIssueValues|BuildUrlMentionValues} BuildUrlValues
+ *
+ * @typedef BuildUrlCommitValues
+ *   Arguments for buildUrl functions for commit hash
+ * @property {'commit'} type The type of special object
+ * @property {string} hash The commit hash value
+ * @property {string} project The project of the repo
+ * @property {string} user The owner of the repo
+ *
+ * @typedef BuildUrlCompareValues
+ *   Arguments for buildUrl functions for commit hash ranges
+ * @property {'compare'} type The type of special object
+ * @property {string} base The SHA of the range start
+ * @property {string} compare The SHA of the range end
+ * @property {string} project The project of the repo
+ * @property {string} user The owner of the repo
+ *
+ * @typedef BuildUrlIssueValues
+ *   Arguments for buildUrl functions for issues
+ * @property {'issue'} type The type of special object
+ * @property {string} no The parsed issue number
+ * @property {string} project The project of the repo
+ * @property {string} user The owner of the repo
+ *
+ * @typedef BuildUrlMentionValues
+ *   Arguments for buildUrl functions for mentions
+ * @property {'mention'} type The type of special object
+ * @property {string} user The parsed user name
+ *
+ * @typedef RepositoryInfo
+ *   The owner and project of the repo
+ * @property {string} project The project/repo name
+ * @property {string} user The user/organization name
+ *
  * @typedef Options
  *   Configuration.
+ * @property {BuildUrl} [buildUrl]
  * @property {boolean} [mentionStrong=true]
  *   Wrap mentions in `<strong>`, true by default.
  *   This makes them render more like how GitHub styles them.
@@ -118,13 +162,23 @@ export default function remarkGithub(options = {}) {
         : ''
   }
 
+  /**
+   * @param {BuildUrlValues} values
+   * @returns {string}
+   */
+  function buildUrl(values) {
+    if (options.buildUrl) return options.buildUrl(values, defaultBuildUrl)
+    return defaultBuildUrl(values)
+  }
+
   // Parse the URL: See the tests for all possible kinds.
   const repositoryMatch = repoRegex.exec(repository || '')
 
   if (!repositoryMatch) {
     throw new Error('Missing `repository` field in `options`')
   }
 
+  /** @type {RepositoryInfo} */
   const repositoryInfo = {user: repositoryMatch[1], project: repositoryMatch[2]}
 
   return (tree) => {
@@ -213,7 +267,7 @@ export default function remarkGithub(options = {}) {
     return {
       type: 'link',
       title: null,
-      url: 'https://github.com/' + username,
+      url: buildUrl({type: 'mention', user: username}),
       children: [node]
     }
   }
@@ -235,13 +289,12 @@ export default function remarkGithub(options = {}) {
     return {
       type: 'link',
       title: null,
-      url:
-        'https://github.com/' +
-        repositoryInfo.user +
-        '/' +
-        repositoryInfo.project +
-        '/issues/' +
+      url: buildUrl({
+        type: 'issue',
         no,
+        project: repositoryInfo.project,
+        user: repositoryInfo.user
+      }),
       children: [{type: 'text', value}]
     }
   }
@@ -265,13 +318,13 @@ export default function remarkGithub(options = {}) {
     return {
       type: 'link',
       title: null,
-      url:
-        'https://github.com/' +
-        repositoryInfo.user +
-        '/' +
-        repositoryInfo.project +
-        '/compare/' +
-        value,
+      url: buildUrl({
+        type: 'compare',
+        base: a,
+        compare: b,
+        project: repositoryInfo.project,
+        user: repositoryInfo.user
+      }),
       children: [{type: 'inlineCode', value: abbr(a) + '...' + abbr(b)}]
     }
   }
@@ -296,13 +349,12 @@ export default function remarkGithub(options = {}) {
     return {
       type: 'link',
       title: null,
-      url:
-        'https://github.com/' +
-        repositoryInfo.user +
-        '/' +
-        repositoryInfo.project +
-        '/commit/' +
-        value,
+      url: buildUrl({
+        type: 'commit',
+        project: repositoryInfo.project,
+        user: repositoryInfo.user,
+        hash: value
+      }),
       children: [{type: 'inlineCode', value: abbr(value)}]
     }
   }
@@ -350,15 +402,19 @@ export default function remarkGithub(options = {}) {
     return {
       type: 'link',
       title: null,
-      url:
-        'https://github.com/' +
-        user +
-        '/' +
-        (project || repositoryInfo.project) +
-        '/' +
-        (no ? 'issues' : 'commit') +
-        '/' +
-        (no || sha),
+      url: no
+        ? buildUrl({
+            type: 'issue',
+            no,
+            project: project || repositoryInfo.project,
+            user
+          })
+        : buildUrl({
+            type: 'commit',
+            hash: sha,
+            project: project || repositoryInfo.project,
+            user
+          }),
       children: nodes
     }
   }
@@ -374,6 +430,34 @@ function abbr(sha) {
   return sha.slice(0, minShaLength)
 }
 
+/**
+ * Given a set of values based on the values type, returns link URL.
+ *
+ * @type {DefaultBuildUrl}
+ */
+function defaultBuildUrl(values) {
+  const base = 'https://github.com'
+
+  if (values.type === 'mention') return [base, values.user].join('/')
+
+  const {project, user} = values
+
+  if (values.type === 'commit')
+    return [base, user, project, 'commit', values.hash].join('/')
+
+  if (values.type === 'issue')
+    return [base, user, project, 'issues', values.no].join('/')
+
+  // This should only run if values.type is 'compare'
+  return [
+    base,
+    user,
+    project,
+    'compare',
+    values.base + '...' + values.compare
+  ].join('/')
+}
+
 /**
  * Parse a link and determine whether it links to GitHub.
  *

package.json

@@ -30,7 +30,8 @@
   "author": "Titus Wormer <[email protected]> (https://wooorm.com)",
   "contributors": [
     "Titus Wormer <[email protected]> (https://wooorm.com)",
-    "Anthony Maki <[email protected]>"
+    "Anthony Maki <[email protected]>",
+    "Ev Haus <[email protected]>"
   ],
   "sideEffects": false,
   "type": "module",

readme.md

@@ -134,6 +134,30 @@ in GitHub issues, PRs, and comments (see
 *   At-mentions:
     `@wooorm` → [**@wooorm**][mention]
 
+##### Custom URLs
+
+By default we build URLs to public GitHub.
+You can overwrite them to point to GitHub Enterprise or other places by passing
+a `buildUrl`.
+That function is given an object with different values and the default
+`buildUrl`.
+
+```js
+remark()
+  .use(remarkGithub, {
+    // The fields in `values` depends on the kind reference:
+    // {type: 'commit', hash, project, user}
+    // {type: 'hashrange', base, compare, project, user}
+    // {type: 'issue', no, project, user}
+    // {type: 'mention', user}
+    buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'mention'
+            ? `https://yourwebsite.com/${values.user}/`
+            : defaultBuildUrl(values)
+    }
+  })
+```
+
 ###### Repository
 
 These links are generated relative to a project.

test/index.js

@@ -177,6 +177,94 @@ test('Repositories', (t) => {
   t.end()
 })
 
+test('Custom URL builder option', (t) => {
+  t.equal(
+    github('@wooorm', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'mention'
+          ? `https://github.yourcompany.com/${values.user}/`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[**@wooorm**](https://github.yourcompany.com/wooorm/)\n',
+    'should support custom `baseUrl` function value for mentions'
+  )
+
+  t.equal(
+    github('#123', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'issue'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/issues/${values.no}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[#123](https://github.yourcompany.com/remarkjs/remark-github/issues/123)\n',
+    'should support custom `baseUrl` function value for issues'
+  )
+
+  t.equal(
+    github('GH-1', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'issue'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/issues/${values.no}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[GH-1](https://github.yourcompany.com/remarkjs/remark-github/issues/1)\n',
+    'should support custom `baseUrl` function value for non-standard issues'
+  )
+
+  t.equal(
+    github('e2acebc...2aa9311', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'compare'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/compare/${values.base}...${values.compare}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[`e2acebc...2aa9311`](https://github.yourcompany.com/remarkjs/remark-github/compare/e2acebc...2aa9311)\n',
+    'should support custom `baseUrl` function value for hash ranges'
+  )
+
+  t.equal(
+    github('1f2a4fb', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'commit'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/commit/${values.hash}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[`1f2a4fb`](https://github.yourcompany.com/remarkjs/remark-github/commit/1f2a4fb)\n',
+    'should support custom `baseUrl` function value for commit hashes'
+  )
+
+  t.equal(
+    github('remarkjs/remark-github#1', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'issue'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/issues/${values.no}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[#1](https://github.yourcompany.com/remarkjs/remark-github/issues/1)\n',
+    'should support custom `baseUrl` function value for cross-project issue references'
+  )
+
+  t.equal(
+    github('remarkjs/remark-github@1f2a4fb', {
+      buildUrl: (values, defaultBuildUrl) => {
+        return values.type === 'commit'
+          ? `https://github.yourcompany.com/${values.user}/${values.project}/commit/${values.hash}`
+          : defaultBuildUrl(values)
+      }
+    }),
+    '[@`1f2a4fb`](https://github.yourcompany.com/remarkjs/remark-github/commit/1f2a4fb)\n',
+    'should support custom `baseUrl` function value for cross-project hash references'
+  )
+
+  t.end()
+})
+
 test('Miscellaneous', (t) => {
   const original = process.cwd()