elm_history_tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9a30716f0cdb540ad8228ec16e82e2e42d1a000f
+  data.tar.gz: 3163afcb272e617cce11a7c4afdfea92db1d801d
+SHA512:
+  metadata.gz: d34ce51ff0aa23cbc2dae2d6dbd5ee5a7cd568e02cd222a43cdf93e049998c5015d1d2be3f3af68ba12701d4b0c7bbc3f0e4a4c6225e60613b36dc83680bed7e
+  data.tar.gz: b1d356d39c1434c69b5520006bd1be06c39efde94ee8ff0096d008f2334371ef683d6cb9d18817a84eef0aa63af69b32dc10cce668768c62da06f92564a42679

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.DS_Store
+.byebug_history

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at alex@alexkoppel.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in elm_history_tools.gemspec
+gemspec
+
+group :development do
+  gem "byebug"
+end
+
+group :test do
+  gem "rspec"
+end

data/Gemfile.lock

@@ -0,0 +1,39 @@
+PATH
+  remote: .
+  specs:
+    elm_history_tools (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    awesome_print (1.8.0)
+    byebug (10.0.2)
+    diff-lcs (1.3)
+    rake (10.5.0)
+    rspec (3.7.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print
+  bundler (~> 1.16)
+  byebug
+  elm_history_tools!
+  rake (~> 10.0)
+  rspec
+
+BUNDLED WITH
+   1.16.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Alex Koppel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# ElmHistoryTools
+
+One of the great aspects of the Elm programming language is its debugger. Because all the possible states of an Elm program are clearly defined and state only changes in response to messages, Elm can track everything that happens -- and make it available to you to debug both.
+
+You can also export this history to a file, allowing your support team and developers to debug a user's session without having to be in the same room. Using a package like [ElmRings](https://github.com/arsduo/elm-rings/), you can even capture this data automatically and upload it to your servers for later use.
+
+Of course, once you have that data on your servers, you'll have to work through two challenges:
+
+1. **Security**: every keystroke of a user’s password and all the sensitive personal information they enter in your app go into Elm’s history. It’s no good hashing passwords on the user model if another table contains them in plain text — you need to sanitize and secure this data carefully if you store it.
+2. **Complicated data structure**: the Elm history data is meant to be imported into Elm more than it's meant to be analyzed by humans. If you want to show your support team what happened in a user session in which an error occurred, you need to make that data presentable.
+
+If you, like me, have these problems, you're in the right place.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elm_history_tools'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install elm_history_tools
+
+
+## Usage
+
+Right now, ElmHistoryTools comes with two utilities:
+
+_Sanitizing History_
+
+**Be careful you don't accidentally expose critical user information** -- it's no good hashing passwords on the user model if an Elm history table contains them in plain text. Before storing
+
+How do you actually do this?
+
+COMING SOON
+
+_Format a History into a Hash_
+
+One approach we've found useful for user issues at eSpark Learning has been to skim the
+history and see if anything looks amiss. Eyeballing the user's actions shows if a student get an unhappy response back from a
+server, if they were able to they answer any quiz questions, etc., providing a useful context for
+further debugging.
+
+In order to make sense of data, it has to be presented in a comprehensible format. That's what the
+`ElmHistoryTools::HistoryFormatter` object can do:
+
+```ruby
+# given a JSON history file like
+# {"history": [{"ctor": "MessageType", "_0": "Arg1", "_02": {"ctor": "AnotherType"}}, {"ctor":"AnotherMessageType", "_0": "AnotherArg"}]}
+
+ElmHistoryTools::HistoryFormatter.to_simple_hash(JSON.parse(history_json))
+
+# will produce
+
+[
+  {"MessageType" => ["Arg1", {"AnotherType" => []}],
+  {"AnotherMessageType" => ["AnotherArg"]}
+]
+```
+
+You can then easily loop over this data in Ruby to present a readable internal dashboard:
+
+<img width="954" alt="elm-history-dashboard" src="https://user-images.githubusercontent.com/48325/39089476-5ae84a92-458d-11e8-9039-489886d17b0b.png">
+
+
+## Elm History Export Format
+
+The Elm 0.18.0 history export is structured as followed:
+
+```js
+{
+  "metadata": {
+    "versions": {"elm": "0.18.0"},
+    "types": {
+      // the Message type used by your program
+      "message": "Message.Message",
+      // all the type aliases defined in your program
+      "aliases": {
+        "Json.Decode.Value": {"args":[],"type":"Json.Encode.Value"},
+        // etc.
+      },
+      // all the union types used in your program
+      "unions": {
+        "Maybe.Maybe": {
+          // what arguments the union type takes
+          "args": ["a"],
+          // what tags/constructors make up that union type and what arguments they take
+          "tags":{
+            "Just": ["a"],
+            "Nothing": []
+          }
+        }
+      }
+    }
+  }
+  // what's happened in user session being exported
+  "history": [
+    // each entry is stored with the contructor and any ordered arguments passed to it
+    {"ctor": "MessageType", "_0": "Arg1", "_02": {"ctor": "AnotherType"}},
+    {"ctor": "AnotherMessageType", "_0": "AnotherArg"},
+    // etc.
+  ]
+}
+```
+
+Each entry in the history hash represents an Elm message object -- so
+
+```js
+{"ctor": "MessageType", "_0": "Arg1", "_02": {"ctor": "AnotherType"}},
+```
+
+represents the Elm message
+
+```elm
+-- if type alias SomeType = AnotherType | SomethingElse
+--
+-- MessageType String SomeType
+MessageType "Arg1" AnotherType
+```
+
+A few notes:
+
+**Lists**
+
+List entries are recursively nested objects whose constructor is `::` (cons).
+
+As an example, an Elm list of three books (`[{title = "Too Like the Lightning"}, {title = "The Fear of Barbarians"}, {title = "Evicted"}]`) would be represented as:
+
+```js
+{
+  "ctor": "::",
+  "_0": {"title": "Too Like the Lightning"},
+  "_1": {
+    "ctor": "::",
+    "_0": {"title": "The Fear of Barbarians"},
+    "_1": {
+      "ctor": "::",
+      "_0": {"title": "Evicted"}
+    }
+  }
+}
+```
+
+This is because in Elm, `List` is implemented as a linked list (each element is an object that both stores its value and points to the next element in the list, rather than sitting in an array of plain values).
+
+You don't need to know anything about linked lists to use Elm (or Javascript or Ruby or, likely, whatever you're using for work or fun -- I've literally never used them in my career), but if you're curious, you can read more about them [on Wikipedia](https://en.wikipedia.org/wiki/Linked_list). You can also check out [this interesting discussion](https://github.com/elm-lang/elm-plans/issues/13) of Arrays vs. Lists in Elm.
+
+**In the future**
+
+It looks like the terms will change somewhat in a future version of Elm:  `"ctor"` and `"_01"`, `"_02"`, etc. will be [replaced with `$`, `a`, `b`, etc](https://github.com/elm-lang/virtual-dom/commit/61cf2090ecb745542532dd7ea87de37c6ed6c3b4#diff-25d902c24283ab8cfbac54dfa101ad31). ElmHistoryTools will support both formats in the future; should the structure change, obviously that will be addressed too.
+
+**Why hashes?**
+
+Why hashes?, you might wonder. Why not use arrays (e.g. `{"MessageType": ["Arg1", {"AnotherType": []}]}` or `["MessageType", "Arg1", ["AnotherType"]]`)? Wouldn't that be simpler?
+
+Turns out you're not the first person to wonder about it. As @evancz [wrote in response to a similar question in 2015](https://groups.google.com/d/msg/elm-dev/pr4d8jUKz9c/bYejb7JOCgAJ):
+
+> I believe in the olden times, I did use an array because I just assumed it'd be fast. I later ran some benchmarks and was totally wrong, objects were a lot faster. So I switched everything.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/arsduo/elm_history_tools. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the ElmHistoryTools project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [Code of Conduct](https://github.com/arsduo/elm_history_tools/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "elm_history_tools"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/elm_history_tools.gemspec

@@ -0,0 +1,23 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "elm_history_tools/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "elm_history_tools"
+  spec.version       = ElmHistoryTools::VERSION
+  spec.authors       = ["Alex Koppel"]
+  spec.email         = ["alex@alexkoppel.com"]
+
+  spec.summary       = %q{Tools to work with Elm history exports.}
+  spec.homepage      = "http://github.com/arsduo/elm-history-tools"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/elm_history_tools.rb

@@ -0,0 +1,6 @@
+require "elm_history_tools/version"
+require "elm_history_tools/history_formatter"
+
+module ElmHistoryTools
+  # Your code goes here...
+end

data/lib/elm_history_tools/history_formatter.rb

@@ -0,0 +1,42 @@
+module ElmHistoryTools::HistoryFormatter
+  # Given a raw Elm history file parsed to JSON, return a simplified hash of the history.
+  #
+  # For instance, given an array like:
+  # [{"ctor": "MessageType", "_0": "Arg1", "_02": {"ctor": "AnotherType"}}]
+  #
+  # you'll get
+  #
+  # [{"MessageType" => ["Arg1", {"AnotherType" => []}]}]
+  #
+  def self.to_simple_hash(history_data)
+    history_data["history"].map do |entry|
+      simplify_history_entry(entry)
+    end
+  end
+
+  # Turn an Elm history entry into a simple Ruby hash, as described above.
+  #
+  # Constructors that take no arguments are represented as taking an empty list (see above); an
+  # alternative approach would be to use nil. While that would clearly distinguish between those
+  # cases, it would make working with the results more complicated.
+  def self.simplify_history_entry(entry)
+    if !entry.is_a?(Hash)
+      entry
+    elsif entry["ctor"] == "::"
+      # Elm lists are represented as nested entries with the contructor ::. (See the readme for
+      # more detail.)
+      # We collapse those into a proper Ruby array via flatten.
+      # The last entry of the list will have no nested entry, so we use compact to remove the nil.
+      [simplify_history_entry(entry["_0"]), simplify_history_entry(entry["_1"])].compact.flatten
+    elsif entry["ctor"]
+      # we have an Elm type
+      {
+        entry["ctor"] => entry.reject {|k, _v| k == "ctor"}.values.map {|val| simplify_history_entry(val) }
+      }
+    else
+      entry.each_with_object({}) do |(key, value), hash|
+        hash[key] = simplify_history_entry(value)
+      end
+    end
+  end
+end

data/lib/elm_history_tools/version.rb

@@ -0,0 +1,3 @@
+module ElmHistoryTools
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: elm_history_tools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alex Koppel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: 
+email:
+- alex@alexkoppel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- elm_history_tools.gemspec
+- lib/elm_history_tools.rb
+- lib/elm_history_tools/history_formatter.rb
+- lib/elm_history_tools/version.rb
+- readme-images/elm-history-dashboard.png
+homepage: http://github.com/arsduo/elm-history-tools
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Tools to work with Elm history exports.
+test_files: []