refactor: allow .json extension on annotations file #836 (#1402)

* refactor: corrected annotations.js to annotations.json

* refactor(annotations): allow .json extension on annotations file #836

* refactor: corrected annotations.js to annotations.json

* feat(annotations): added at least annotation to the sample content

* chore: added another annotations example

* refactor(docs): corrected the filetype in the docs as well

* docs(annotations): added further details

* refactor: removed this file again for the moment

* refactor: renamed this file (after the latest merge)

* refactor: migrated that file as well

Co-authored-by: Josef Bredreck <[email protected]>

packages/core/src/lib/annotation_exporter.js → packages/core/src/lib/annotationExporter.js

@@ -6,39 +6,47 @@ const _ = require('lodash');
 const mp = require('./markdown_parser');
 const logger = require('./log');
 
-const annotations_exporter = function (pl) {
+const annotationExporter = function (pl) {
   const paths = pl.config.paths;
-  let oldAnnotations;
 
   /**
    * Parses JS annotations.
    * @returns array of comments that used to be wrapped in raw JS
    */
-  function parseAnnotationsJS() {
+  function parseAnnotationsJSON() {
+    const jsonPath = path.resolve(paths.source.annotations, 'annotations.json');
+    let annotations;
+
     //attempt to read the file
     try {
-      oldAnnotations = fs.readFileSync(
-        path.resolve(paths.source.annotations, 'annotations.js'),
-        'utf8'
-      );
+      if (fs.pathExistsSync(jsonPath)) {
+        //read the new file
+        annotations = fs.readFileSync(jsonPath, 'utf8');
+      } else {
+        //read the old file
+        const jsPath = path.resolve(paths.source.annotations, 'annotations.js');
+
+        annotations = fs
+          .readFileSync(jsPath, 'utf8')
+          .replace(/^\s*var comments ?= ?/, '')
+          .replace(/};\s*$/, '}');
+
+        logger.info(
+          `Please convert ${jsPath} to JSON and rename it annotations.json.`
+        );
+      }
     } catch (ex) {
       logger.debug(
-        `annotations.js file missing from ${paths.source.annotations}. This may be expected if you do not use annotations or are using markdown.`
+        `annotations.json file missing from ${paths.source.annotations}. This may be expected if you do not use annotations or are using markdown.`
       );
       return [];
     }
 
-    //parse as JSON by removing the old wrapping js syntax. comments and the trailing semi-colon
-    oldAnnotations = oldAnnotations.replace('var comments = ', '');
-    oldAnnotations = oldAnnotations.replace('};', '}');
-
     try {
-      const oldAnnotationsJSON = JSON.parse(oldAnnotations);
-      return oldAnnotationsJSON.comments;
+      const annotationsJSON = JSON.parse(annotations);
+      return annotationsJSON.comments;
     } catch (ex) {
-      logger.error(
-        `There was an error parsing JSON for ${paths.source.annotations}annotations.js`
-      );
+      logger.error(`There was an error parsing JSON for ${jsonPath}`);
       return [];
     }
   }
@@ -104,7 +112,7 @@ const annotations_exporter = function (pl) {
    * @returns array of annotations
    */
   function gatherAnnotations() {
-    const annotationsJS = parseAnnotationsJS();
+    const annotationsJS = parseAnnotationsJSON();
     const annotationsMD = parseAnnotationsMD();
     return _.unionBy(annotationsJS, annotationsMD, 'el');
   }
@@ -113,13 +121,13 @@ const annotations_exporter = function (pl) {
     gather: function () {
       return gatherAnnotations();
     },
-    gatherJS: function () {
-      return parseAnnotationsJS();
+    gatherJSON: function () {
+      return parseAnnotationsJSON();
     },
     gatherMD: function () {
       return parseAnnotationsMD();
     },
   };
 };
 
-module.exports = annotations_exporter;
+module.exports = annotationExporter;

packages/core/src/lib/exportData.js

@@ -3,7 +3,7 @@
 const path = require('path');
 const eol = require('os').EOL;
 
-const ae = require('./annotation_exporter');
+const ae = require('./annotationExporter');
 
 let fs = require('fs-extra'); //eslint-disable-line prefer-const
 
@@ -12,7 +12,7 @@ let fs = require('fs-extra'); //eslint-disable-line prefer-const
  * @param patternlab - global data store
  */
 module.exports = function (patternlab, uikit) {
-  const annotation_exporter = new ae(patternlab);
+  const annotationExporter = new ae(patternlab);
 
   const paths = patternlab.config.paths;
 
@@ -67,7 +67,7 @@ module.exports = function (patternlab, uikit) {
     eol;
 
   //annotations
-  const annotationsJSON = annotation_exporter.gather();
+  const annotationsJSON = annotationExporter.gather();
   const annotations =
     'var comments = { "comments" : ' + JSON.stringify(annotationsJSON) + '};';
   fs.outputFileSync(

packages/core/test/annotation_exporter_tests.js

@@ -20,12 +20,12 @@ function createFakePatternLab(anPath, customProps) {
 }
 
 var patternlab = createFakePatternLab(anPath);
-var ae = require('../src/lib/annotation_exporter')(patternlab);
+var ae = require('../src/lib/annotationExporter')(patternlab);
 
 tap.test('converts old JS annotations into new format', function (test) {
   //arrange
   //act
-  var annotations = ae.gatherJS();
+  var annotations = ae.gatherJSON();
 
   //assert
   test.equal(annotations.length, 2);
@@ -77,7 +77,7 @@ tap.test('merges both annotation methods into one array', function (test) {
 tap.test('when there are 0 annotation files', function (test) {
   var emptyAnPath = './test/files/empty/';
   var patternlab2 = createFakePatternLab(emptyAnPath);
-  var ae2 = require('../src/lib/annotation_exporter')(patternlab2);
+  var ae2 = require('../src/lib/annotationExporter')(patternlab2);
 
   var annotations = ae2.gather();
   test.equal(annotations.length, 0);

packages/development-edition-engine-handlebars/source/_annotations/annotations.json

@@ -0,0 +1,3 @@
+{
+  "comments": []
+}

packages/docs/src/docs/pattern-adding-annotations.md

@@ -10,7 +10,7 @@ eleventyNavigation:
 sitemapPriority: '0.8'
 ---
 
-Annotations provide an easy way to add notes to elements that may appear inside patterns. Annotations can be saved as a single JSON file at `./source/_annotations/annotations.js` or as multiple Markdown files in `./source/_annotations/`. They're _not_ tied to any specific patterns. When annotations are active they are compared against every pattern using a CSS selector syntax.
+Annotations provide an easy way to add notes to elements that may appear inside patterns. Annotations can be saved as a single JSON file at `./source/_annotations/annotations.json` or as multiple Markdown files in `./source/_annotations/`. They're _not_ tied to any specific patterns. When annotations are active they are compared against every pattern using a CSS selector syntax.
 
 ## The Elements of an Annotation
 
@@ -22,7 +22,7 @@ The elements of an annotation are:
 
 ## JSON Example
 
-This is an example of an annotation saved as part of `annotations.js` that will be added to an element with the class `logo`:
+This is an example of an annotation saved as part of `annotations.json` that will be added to an element with the class `logo`:
 
 ```javascript
 {
@@ -32,6 +32,8 @@ This is an example of an annotation saved as part of `annotations.js` that will
 }
 ```
 
+Compare to e.g. [`handlebars` annotations](https://github.com/pattern-lab/patternlab-node/blob/dev/packages/starterkit-handlebars-demo/dist/_annotations/annotations.json) or [`twig` annotations](https://github.com/pattern-lab/patternlab-node/blob/dev/packages/starterkit-twig-demo/dist/_annotations/annotations.json) editions demo content as well.
+
 ## Markdown Example
 
 This is an example of an annotation saved as part of `annotations.md` that will be added to an element with the class `logo`:

packages/starterkit-handlebars-demo/dist/_annotations/annotations.js → packages/starterkit-handlebars-demo/dist/_annotations/annotations.json

@@ -1,4 +1,4 @@
-var comments = {
+{
   "comments" : [
     {
       "el": ".c-header",
@@ -11,4 +11,4 @@ var comments = {
       "comment": "The logo isn't an image but regular text, which ensures that the logo displays crisply even on high resolution displays."
     }
   ]
-};
+}