Add prettier support, via 'npm run format'

.eslintrc.js

@@ -2,30 +2,24 @@
 
 module.exports = {
   env: {
-    "node": true
+    node: true,
   },
-  extends: [
-    "eslint:recommended",
-    "plugin:mozilla/recommended",
-  ],
+  extends: ["eslint:recommended", "plugin:mozilla/recommended"],
 
-  plugins: [
-    "mozilla",
-    "json"
-  ],
+  plugins: ["mozilla", "json"],
 
   rules: {
     "babel/new-cap": "off",
     "comma-dangle": ["error", "always-multiline"],
-    "eqeqeq": "error",
-    "indent": ["warn", 2, {SwitchCase: 1}],
+    eqeqeq: "error",
+    indent: ["warn", 2, { SwitchCase: 1 }],
     "mozilla/no-aArgs": "warn",
     "mozilla/balanced-listeners": 0,
     "no-console": "warn",
     "no-debugger": "warn",
     "no-shadow": ["error"],
     "no-unused-vars": "error",
     "prefer-const": "warn",
-    "semi": ["error", "always"],
+    semi: ["error", "always"],
   },
 };

.prettierignore

@@ -0,0 +1,3 @@
+package-lock.json
+docs/css
+package.json

README.md

@@ -1,27 +1,34 @@
-| index | [example]     |
-|-------|---------------|
+| index | [example] |
+| ----- | --------- |
 
 
 # Shield Studies Addon Utils [![Build Status](https://travis-ci.org/tombell/travis-ci-status.svg?branch=master)](https://travis-ci.org/tombell/travis-ci-status)
 
-- Instrument your Firefox Addon!
-- Build Shield Study (Normandy) compatible addons without having to think very much.
+* Instrument your Firefox Addon!
+* Build Shield Study (Normandy) compatible addons without having to think very
+  much.
 
 ## Assumptions
 
-- You are building a [LEGACY ADDONS](https://developer.mozilla.org/en-US/Add-ons/Legacy_add_ons).  To deploy these after 57, you will need the magic special signing.
--  Jetpack / addon-sdk is NOT SUPPORTED.
-- WebExtensions are not strong enough
+* You are building a
+  [LEGACY ADDONS](https://developer.mozilla.org/en-US/Add-ons/Legacy_add_ons).
+  To deploy these after 57, you will need the magic special signing.
+* Jetpack / addon-sdk is NOT SUPPORTED.
+* WebExtensions are not strong enough
 
 ## history of major versions
 
-- v4.x: (proposed)  additional functions for common cases
-- v4: First `.jsm` release.  Uses packet format for PACKET version 3.
-- v3: Attempt to formalize on `shield-study` PACKET version 3.  Jetpack based.  Prototype used for `raymak/page-reload`.  All work abandoned, and no formal npm release in this series.  Work done at `v3-shield-packet-format` branch.  LAST JETPACK (addon-sdk) RELEASE.
-s v2: Code refactor to es6 `class` with event models.  Added cli tooling.  Packet format is still arbitrary and per-study.  Jetpack based.  Last used in studies in Q2 2017.
-- v1: Initial work and thinking.  Telemetry packets are rather arbitrary.  Jetpack based.
-
-
+* v4.x: (proposed) additional functions for common cases
+* v4: First `.jsm` release. Uses packet format for PACKET version 3.
+* v3: Attempt to formalize on `shield-study` PACKET version 3. Jetpack based.
+  Prototype used for `raymak/page-reload`. All work abandoned, and no formal npm
+  release in this series. Work done at `v3-shield-packet-format` branch. LAST
+  JETPACK (addon-sdk) RELEASE.
+* v2: Code refactor to es6 `class` with event models. Added cli tooling. Packet
+  format is still arbitrary and per-study. Jetpack based. Last used in studies
+  in Q2 2017.
+* v1: Initial work and thinking. Telemetry packets are rather arbitrary. Jetpack
+  based.
 
 ## install
 
@@ -31,45 +38,43 @@ npm install --save-dev shield-studies-addon-utils
 
 Copy the file to somewhere useful in your addon.
 
-
 ## Tutorial and Full Usage
 
 [fully worked tutorial - How To Shield Study](./howToShieldStudy.md)
 
 ## Example embedded web extension study
 
-See [examples](https://github.com/mozilla/shield-studies-addon-utils/tree/master/examples) directory.
+See
+[examples](https://github.com/mozilla/shield-studies-addon-utils/tree/master/examples)
+directory.
 
 ## Summary
 
 ### Design Case
 
 Your Study is:
 
-- side-by-side variations (1 or more)
+* side-by-side variations (1 or more)
 
 ### Benefits
 
 Using this, you get this analysis FOR FREE (and it's fast!)
 
-- Branch x channel x VARIATION x experiment-id x PHASE (install, reject, alive etc) using UNIFIED TELEMETRY
-
+* Branch x channel x VARIATION x experiment-id x PHASE (install, reject, alive
+  etc) using UNIFIED TELEMETRY
 
 ## Development
 
-- open an issue
-- hack and file a PR
-
+* open an issue
+* hack and file a PR
 
 ## Gotchas, Opinions, Side Effects, and Misfeatures
 
-1.  No handling of 'timers'.  No saved state at all (including the variation name), unless you handle it yourself.
-
-2.  No 'running' pings in v4 (yet).
+1. No handling of 'timers'. No saved state at all (including the variation
+   name), unless you handle it yourself.
 
-3.  User disable also uninstalls (and cleans up)
+2. No 'running' pings in v4 (yet).
 
+3. User disable also uninstalls (and cleans up)
 
 [example]: examples/README.md
-
-

examples/README.md

@@ -2,6 +2,5 @@
 
 Demonstrated in stages.
 
-- stage 1:  embedded web extension
-- stage 2:  instrumented shield study
-
+* stage 1: embedded web extension
+* stage 2: instrumented shield study

examples/stage-2-shield-study/.eslintrc.js

@@ -1,29 +1,22 @@
 "use strict";
 
 module.exports = {
-  env: {
-  },
-  extends: [
-    "eslint:recommended",
-    "plugin:mozilla/recommended",
-  ],
+  env: {},
+  extends: ["eslint:recommended", "plugin:mozilla/recommended"],
 
-  plugins: [
-    "mozilla",
-    "json"
-  ],
+  plugins: ["mozilla", "json"],
 
   rules: {
     "babel/new-cap": "off",
     "comma-dangle": ["error", "always-multiline"],
-    "eqeqeq": "error",
-    "indent": ["warn", 2, {SwitchCase: 1}],
+    eqeqeq: "error",
+    indent: ["warn", 2, { SwitchCase: 1 }],
     "mozilla/no-aArgs": "warn",
     "mozilla/balanced-listeners": 0,
     "no-console": "warn",
     "no-shadow": ["error"],
     "no-unused-vars": "error",
     "prefer-const": "warn",
-    "semi": ["error", "always"],
+    semi: ["error", "always"],
   },
 };

examples/stage-2-shield-study/README.md

@@ -2,41 +2,45 @@
 
 ## install
 
-`npm install`
-`npm run build`
-
+```sh
+npm install
+npm run build
+```
 
 at second shell/prompt, watch files for changes to rebuild:
 
 `npm run watch`
 
-
 ## in Firefox:
 
-1. `about:debugging > [load temporary addon] > choose `dist/addon.xpi`
+1. `about:debugging > [load temporary addon] > choose 'dist/addon.xpi'`
 2. `tools > Web Developer > Browser Toolbox`
 
 ## Effects:
 
-1.  See a new button (with a 'puzzle piece') symbol.
-2.  to end early:  Click on button multiple times until the 'too-popular' endpoint is reached.
+1. See a new button (with a 'puzzle piece') symbol.
+2. To end early: Click on button multiple times until the 'too-popular' endpoint
+   is reached.
 
 ## Further extensions / modifications
 
-1.  (TBD)
+1. (TBD)
 
 ## Description of architecture
 
-Embedded Web Extension (`/webextension/`) lives inside a restartless (`bootstrap.js`) extension.
+Embedded Web Extension (`/webextension/`) lives inside a restartless
+(`bootstrap.js`) extension.
 
 During `bootstrap.js:startup(data, reason)`:
 
-    a. `shieldUtils` imports and sets configuration from `Config.jsm`
-    b. `bootstrap.js:chooseVariation` explicitly and deterministically chooses a variation from `studyConfig.weightedVariations`
-    c.  the WebExtension starts up
-    d.  `boostrap.js` listens for requests from the `webExtension` that are study related:  `["info", "telemetry", "endStudy"]`
-    e.  `webExtension` (`background.js`) asks for `info` from `studyUtils` using `askShield` function.
-    f.  Feature starts using the `variation` from that info.
-    g.  Feature instruments user button to send `telemetry` and to `endStudy` if the button is clicked enough.
-
-
+* `shieldUtils` imports and sets configuration from `Config.jsm`.
+* `bootstrap.js:chooseVariation` explicitly and deterministically chooses a
+  variation from `studyConfig.weightedVariations`.
+* the WebExtension starts up.
+* `boostrap.js` listens for requests from the `webExtension` that are study
+  related: `["info", "telemetry", "endStudy"]`.
+* `webExtension` (`background.js`) asks for `info` from `studyUtils` using
+  `askShield` function.
+* Feature starts using the `variation` from that info.
+* Feature instruments user button to send `telemetry` and to `endStudy` if the
+  button is clicked enough.

examples/stage-2-shield-study/addon/Config.jsm

@@ -13,72 +13,79 @@ var EXPORTED_SYMBOLS = ["config"];
 // var slug = "shield-example-addon"; // should match chrome.manifest;
 
 var config = {
-  "study": {
-    "studyName": "mostImportantExperiment", // no spaces, for all the reasons
-    "variation": {
-      "name": "kittens",
+  study: {
+    studyName: "mostImportantExperiment", // no spaces, for all the reasons
+    variation: {
+      name: "kittens",
     }, // optional, use to override/decide
-    "weightedVariations": [
-      {"name": "control",
-        "weight": 1},
-      {"name": "kittens",
-        "weight": 1.5},
-      {"name": "puppers",
-        "weight": 2},  // we want more puppers in our sample
+    weightedVariations: [
+      {
+        name: "control",
+        weight: 1,
+      },
+      {
+        name: "kittens",
+        weight: 1.5,
+      },
+      {
+        name: "puppers",
+        weight: 2,
+      }, // we want more puppers in our sample
     ],
     /** **endings**
-      * - keys indicate the 'endStudy' even that opens these.
-      * - urls should be static (data) or external, because they have to
-      *   survive uninstall
-      * - If there is no key for an endStudy reason, no url will open.
-      * - usually surveys, orientations, explanations
-      */
-    "endings": {
+     * - keys indicate the 'endStudy' even that opens these.
+     * - urls should be static (data) or external, because they have to
+     *   survive uninstall
+     * - If there is no key for an endStudy reason, no url will open.
+     * - usually surveys, orientations, explanations
+     */
+    endings: {
       /** standard endings */
       "user-disable": {
-        "baseUrl": "data:,You uninstalled",
+        baseUrl: "data:,You uninstalled",
       },
-      "ineligible": {
-        "baseUrl": "http://www.example.com/?reason=ineligible",
+      ineligible: {
+        baseUrl: "http://www.example.com/?reason=ineligible",
       },
-      "expired": {
-        "baseUrl": "http://www.example.com/?reason=expired",
+      expired: {
+        baseUrl: "http://www.example.com/?reason=expired",
       },
       /** User defined endings */
       "too-popular": {
         // data uri made using `datauri-cli`
-        "baseUrl": "data:text/html;base64,PGh0bWw+CiAgPGJvZHk+CiAgICA8cD5Zb3UgYXJlIHVzaW5nIHRoaXMgZmVhdHVyZSA8c3Ryb25nPlNPIE1VQ0g8L3N0cm9uZz4gdGhhdCB3ZSBrbm93IHlvdSBsb3ZlIGl0IQogICAgPC9wPgogICAgPHA+VGhlIEV4cGVyaW1lbnQgaXMgb3ZlciBhbmQgd2UgYXJlIFVOSU5TVEFMTElORwogICAgPC9wPgogIDwvYm9keT4KPC9odG1sPgo=",
-        "study_state": "ended-positive",  // neutral is default
+        baseUrl:
+          "data:text/html;base64,PGh0bWw+CiAgPGJvZHk+CiAgICA8cD5Zb3UgYXJlIHVzaW5nIHRoaXMgZmVhdHVyZSA8c3Ryb25nPlNPIE1VQ0g8L3N0cm9uZz4gdGhhdCB3ZSBrbm93IHlvdSBsb3ZlIGl0IQogICAgPC9wPgogICAgPHA+VGhlIEV4cGVyaW1lbnQgaXMgb3ZlciBhbmQgd2UgYXJlIFVOSU5TVEFMTElORwogICAgPC9wPgogIDwvYm9keT4KPC9odG1sPgo=",
+        study_state: "ended-positive", // neutral is default
       },
       "a-non-url-opening-ending": {
-        "study_state": "ended-neutral",
-        "baseUrl":  null,
+        study_state: "ended-neutral",
+        baseUrl: null,
       },
     },
-    "telemetry": {
-      "send": true, // assumed false. Actually send pings?
-      "removeTestingFlag": false,  // Marks pings as testing, set true for actual release
+    telemetry: {
+      send: true, // assumed false. Actually send pings?
+      removeTestingFlag: false, // Marks pings as testing, set true for actual release
       // TODO "onInvalid": "throw"  // invalid packet for schema?  throw||log
     },
-    "studyUtilsPath": `./StudyUtils.jsm`,
+    studyUtilsPath: `./StudyUtils.jsm`,
   },
-  "isEligible": async function() {
+  isEligible: async function() {
     // get whatever prefs, addons, telemetry, anything!
     // Cu.import can see 'firefox things', but not package things.
     return true;
   },
   // addon-specific modules to load/unload during `startup`, `shutdown`
-  "modules": [
+  modules: [
     // can use ${slug} here for example
   ],
   // sets the logging for BOTH the bootstrap file AND shield-study-utils
-  "log": {
+  log: {
     // Fatal: 70, Error: 60, Warn: 50, Info: 40, Config: 30, Debug: 20, Trace: 10, All: -1,
-    "bootstrap":  {
-      "level": "Debug",
+    bootstrap: {
+      level: "Debug",
     },
-    "studyUtils":  {
-      "level": "Trace",
+    studyUtils: {
+      level: "Trace",
     },
   },
 };