Add @rawurl special-variable to "withPackageOf"-helper

This variable can be used to reference the a file directly on
https://raw.githubusercontent.com, the reason for adding it was the
usage-examples in `thought-plugin-bootprint`. The url is used as part
of the example command-line in this plugin.

docs/helpers.md

@@ -185,6 +185,7 @@ Set special variable for accessing information from the context of a file (possi
 This block helper executes the block in the current context but sets special variables:
 
 * `@url`: The github-url of the given file in the current package version is stored into
+* `@rawUrl`: The url to the raw file contents on `https://raw.githubusercontent.com`
 * `@package`: The `package.json` of the file's module is stored into
 * `@relativePath`: The relative path of the file within the repository
 

handlebars/helpers/index.js

@@ -213,6 +213,7 @@ function renderTree (object, options) {
  * This block helper executes the block in the current context but sets special variables:
  *
  * * `@url`: The github-url of the given file in the current package version is stored into
+ * * `@rawUrl`: The url to the raw file contents on `https://raw.githubusercontent.com`
  * * `@package`: The `package.json` of the file's module is stored into
  * * `@relativePath`: The relative path of the file within the repository
  *
@@ -228,6 +229,7 @@ function withPackageOf (filePath, options) {
       data.url = _githubUrl(resolvedPackageRoot)
       data.package = resolvedPackageRoot.packageJson
       data.relativePath = resolvedPackageRoot.relativeFile
+      data.rawUrl = _rawGithubUrl(resolvedPackageRoot)
       return options.fn(this, {data: data})
     })
 }
@@ -401,9 +403,9 @@ function repoWebUrl (gitUrl) {
   if (!gitUrl) {
     return undefined
   }
-  const match = gitUrl.match(/.*?(:\/\/|@)github\.com[/:](.*?)(#.*?)?$/)
-  if (match) {
-    return 'https://github.com/' + match[2].replace(/\.git$/, '')
+  const orgRepo = _githubOrgRepo(gitUrl)
+  if (orgRepo) {
+    return 'https://github.com/' + orgRepo
   } else {
     return null
   }
@@ -470,3 +472,29 @@ function _githubUrl (resolvedPackageRoot) {
     return `${url}/blob/v${packageJson.version}/${relativeFile}`
   }
 }
+
+/**
+ * Return the raw url of a file in a githb repository
+ * @private
+ */
+function _rawGithubUrl (resolvedPackageRoot) {
+  var {packageJson, relativeFile} = resolvedPackageRoot
+  const orgRepo = _githubOrgRepo(packageJson && packageJson.repository && packageJson.repository.url)
+  if (orgRepo) {
+    return `https://raw.githubusercontent.com/${orgRepo}/v${packageJson.version}/${relativeFile}`
+  }
+}
+
+/**
+ * Returns the "org/repo"-part of a github url
+ * @param {string=} gitUrl the full repository url
+ * @return {string|null} org and repository, separated by a "/"
+ * @private
+ */
+function _githubOrgRepo (gitUrl) {
+  if (!gitUrl) {
+    return null
+  }
+  const match = gitUrl.match(/.*?(:\/\/|@)github\.com[/:](.*?)(#.*?)?$/)
+  return match && match[2] && match[2].replace(/\.git$/, '')
+}

test/helper-spec.js

@@ -290,6 +290,14 @@ describe('thought-helpers:', function () {
         .to.eventually.equal(versions(fixture('include/withPackageOf.default.md')))
     })
 
+    it('should create a rawUrl for file on github (based on the current package version)', function () {
+      return expectHbs(
+        '{{#withPackageOf file}}{{@rawUrl}}{{/withPackageOf}}',
+        {file: 'test/fixtures/shout.js'}
+      )
+        .to.eventually.equal(versions('https://raw.githubusercontent.com/nknapp/thought/THOUGHT_VERSION/test/fixtures/shout.js'))
+    })
+
     it('should create a url and package.json for file on github (with a git-ssh-url)', function () {
       return expectHbs(
         '{{#withPackageOf file}} {{@url}} - {{@package.name}} {{/withPackageOf}}',
@@ -298,22 +306,38 @@ describe('thought-helpers:', function () {
         .to.eventually.equal(versions(fixture('include/withPackageOf.ssh.md')))
     })
 
-    it('should create a url and package.json for files in dependency projects (based on the their current package version)', function () {
+    it('should create a rawurl file on github (with a git-ssh-url)', function () {
       return expectHbs(
-        '{{#withPackageOf file}} {{@url}} - {{@package.name}} {{/withPackageOf}}',
+        '{{#withPackageOf file}}{{@rawUrl}}{{/withPackageOf}}',
+        {file: 'test/fixtures/github-ssh-repo-url/package.json'}
+      )
+        .to.eventually.equal(versions('https://raw.githubusercontent.com/nknapp/thought-plugin-jsdoc/v1.0.0/package.json'))
+    })
+
+    it('should create a rawUrl for files in dependency projects (based on the their current package version)', function () {
+      return expectHbs(
+        '{{#withPackageOf file}}{{@rawUrl}}{{/withPackageOf}}',
         {file: require.resolve('customize/helpers-io.js')}
       )
-        .to.eventually.equal(versions(fixture('include/withPackageOf.dependency.md')))
+        .to.eventually.equal(versions('https://raw.githubusercontent.com/bootprint/customize/CUSTOMIZE_VERSION/helpers-io.js'))
     })
 
-    it('should not create an url for files without repository-property in the pacakge.json', function () {
+    it('should not create an url for files without repository-property in the package.json', function () {
       return expectHbs(
         '{{#withPackageOf file}} {{@url}} - {{@package.name}} {{/withPackageOf}}',
         {file: require.resolve('./fixtures/no-git-repo/package.json')}
       )
         .to.eventually.equal(versions(fixture('include/withPackageOf.no-repo.md')))
     })
 
+    it('should not create a rawUrl for files without repository-property in the package.json', function () {
+      return expectHbs(
+        '{{#withPackageOf file}}{{@rawUrl}}{{/withPackageOf}}',
+        {file: require.resolve('./fixtures/no-git-repo/package.json')}
+      )
+        .to.eventually.equal('')
+    })
+
     it('should create a @relativePath for files in dependency projects', function () {
       return expectHbs(
         '{{#withPackageOf file}}{{@relativePath}}{{/withPackageOf}}',