feat: add comments to policy files

lib/parser/add-comments.js

@@ -0,0 +1,28 @@
+module.exports = addComments;
+
+var initialComment = 'Snyk (https://snyk.io) policy file, patches or ignores ' +
+                     'known vulnerabilities.';
+var inlineComments = {
+  ignore: 'ignores vulnerabilities until expiry date; change duration by ' +
+          'modifying expiry date',
+  patch: 'patches apply the minimum changes required to fix a vulnerability',
+};
+
+function addComment(source, comment, position) {
+  return source.substr(0, position) + '# ' + comment + '\n' +
+         source.substr(position);
+}
+
+function addComments(policyExport) {
+  policyExport = addComment(policyExport, initialComment, 0);
+
+  Object.keys(inlineComments).forEach(function (key) {
+    var comment = inlineComments[key];
+    var position = policyExport.indexOf('\n' + key + ':\n');
+    if (position !== -1) {
+      policyExport = addComment(policyExport, comment, position + 1);
+    }
+  });
+
+  return policyExport;
+}

lib/parser/index.js

@@ -2,6 +2,7 @@ var path = require('path');
 var cloneDeep = require('lodash.clonedeep');
 var semver = require('semver');
 var yaml = require('js-yaml');
+var addComments = require('./add-comments');
 
 module.exports = {
   import: imports,
@@ -59,7 +60,8 @@ function exports(policy) {
 
   // ensure we always update the version of the policy format
   data.version = version();
-  return yaml.safeDump(data);
+  // put inline comments into the exported yaml file
+  return addComments(yaml.safeDump(data));
 }
 
 function version() {

test/fixtures/ignore/.snyk

@@ -1,3 +1,5 @@
+# Snyk (https://snyk.io) policy file, patches or ignores known vulnerabilities.
+# ignores vulnerabilities until expiry date; change duration by modifying expiry date
 ignore:
   'npm:hawk:20160119':
     - sqlite > sqlite3 > node-pre-gyp > request > hawk:

test/unit/policy-save.test.js

@@ -32,5 +32,7 @@ test('policy.save', function (t) {
       t.equal(writeSpy.args[0][0], filename, 'filename correct');
       var parsed = writeSpy.args[0][1].trim();
       t.equal(parsed, asText, 'body contains original');
+      t.match(parsed, '# Snyk (https://snyk.io) policy file, patches or ' +
+              'ignores known vulnerabilities.', 'body contains comments');
     });
 });