github-to-canvas-quiz 0.1.0

data/lib/github_to_canvas_quiz/parser/markdown/helpers/node_scanner.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  module Parser
+    module Markdown
+      module Helpers
+        # Loosely based on the Ruby `StringScanner` class. Allows position-based
+        # traversal of a `Nokogiri::XML::NodeSet`:
+        #
+        #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+        #   scanner = HTML::Scanner.new(html)
+        #
+        #   # scan and return nodes before the first H3
+        #   nodes = scanner.scan_before('h3')
+        #   nodes.first.content # => 'Hello'
+        #   nodes.last.content  # => 'World'
+        #   scanner.cursor      # => 2
+        #
+        #   # scan the current node if it is a H3
+        #   h3 = scanner.scan('h3')
+        #   h3.content          # => 'end.'
+        #   scanner.eof?        # => true
+        class NodeScanner
+          attr_reader :node_set
+          attr_accessor :cursor
+
+          #
+          # Create a new instance from a Nokogiri::XML::NodeSet or HTML string
+          #
+          # @param [Nokogiri::XML::NodeSet, String] node_set HTML nodes to be scanned
+          #
+          def initialize(nodes)
+            case nodes
+            when Nokogiri::XML::NodeSet
+              @node_set = nodes
+            when String
+              @node_set = Nokogiri::HTML5.fragment(nodes).children
+            else
+              raise TypeError, "expected a Nokogiri::XML::NodeSet or String, got #{nodes.class.name}"
+            end
+
+            @cursor = 0
+          end
+
+          # Returns whether or not the scanner is at the end of the `node_set`
+          def eof?
+            cursor >= node_set.length
+          end
+
+          # Returns the node at the current cursor position
+          def current
+            node_set[cursor]
+          end
+
+          # Scans the current node to see if it matches the selector. If it does,
+          # update the cursor position to the index **after** the found node and
+          # returns the found node. Otherwise, return `nil`.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   h1 = scanner.scan('h1')
+          #   h1.content     # => 'Hello'
+          #   scanner.cursor # => 1
+          def scan(selector)
+            scanned_node = current
+            return unless scanned_node.matches?(selector)
+
+            self.cursor += 1
+            scanned_node
+          end
+
+          # Scans until the node matching the selector is reached, and updates the
+          # cursor position to the index **after** the matched node.
+          #
+          # Returns a `NodeSet` of all nodes between the previous cursor position
+          # and the found node.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   nodes = scanner.scan_until('h2')
+          #   nodes.last.content  # => 'World'
+          #   scanner.cursor      # => 2
+          def scan_until(selector)
+            scan_cursor = cursor
+            while scan_cursor < node_set.length
+              if node_set[scan_cursor].matches?(selector)
+                found_nodes = node_set[cursor..scan_cursor]
+                self.cursor = scan_cursor + 1
+                return found_nodes
+              end
+
+              scan_cursor += 1
+            end
+          end
+
+          # Scans until the node matching the selector is reached, and updates the
+          # cursor position to the index **of** the matched node.
+          #
+          # Returns a `NodeSet` of all nodes between the previous cursor position
+          # and **before** the found node.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   nodes = scanner.scan_before('h2')
+          #   nodes.last.content  # => 'Hello'
+          #   scanner.cursor      # => 1
+          def scan_before(selector)
+            scan_cursor = cursor + 1
+            while scan_cursor < node_set.length
+              if node_set[scan_cursor].matches?(selector)
+                found_nodes = node_set[cursor..scan_cursor - 1]
+                self.cursor = scan_cursor
+                return found_nodes
+              end
+
+              scan_cursor += 1
+            end
+          end
+
+          # Scans until the end of the node set, and updates the cursor position to the end.
+          # Returns a `NodeSet` of all the nodes between the cursor position and the end.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   nodes = scanner.scan_before('h2')
+          #   nodes.last.content  # => 'Hello'
+          #   scanner.cursor      # => 1
+          #   nodes = scanner.scan_rest
+          #   nodes.last.content  # => 'end.
+          #   scanner.cursor      # => 3
+          def scan_rest
+            found_nodes = node_set[cursor..node_set.length - 1]
+            self.cursor = node_set.length
+            found_nodes
+          end
+
+          # Does not update cursor. Checks the current node to see if it matches the selector.
+          # If it does, returns the found node. Otherwise, returns `nil`.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   h1 = scanner.check('h1')
+          #   h1.content     # => 'Hello'
+          #   scanner.cursor # => 0
+          def check(selector)
+            return if eof? || !current.matches?(selector)
+
+            current
+          end
+
+          # Does not update cursor. Checks until the node matching the selector is reached, and
+          # updates the cursor position to the index **after** the matched node.
+          #
+          # Returns a `NodeSet` of all nodes between the previous cursor position
+          # and the found node.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   nodes = scanner.check_until('h2')
+          #   nodes.last.content  # => 'World'
+          #   scanner.cursor      # => 0
+          def check_until(selector)
+            scan_cursor = cursor
+            while scan_cursor < node_set.length
+              if node_set[scan_cursor].matches?(selector)
+                found_nodes = node_set[cursor..scan_cursor]
+                return found_nodes
+              end
+
+              scan_cursor += 1
+            end
+          end
+
+          # Does not update cursor. Checks until the node matching the selector is reached,
+          # and updates the cursor position to the index **of** the matched node.
+          #
+          # Returns a `NodeSet` of all nodes between the previous cursor position
+          # and **before** the found node.
+          #
+          #   html = '<h1>Hello</h1><h2>World</h2><h3>end.</h3>'
+          #   scanner = HTML::Scanner.new(html)
+          #
+          #   nodes = scanner.check_before('h2')
+          #   nodes.last.content  # => 'Hello'
+          #   scanner.cursor      # => 0
+          def check_before(selector)
+            scan_cursor = cursor + 1
+            while scan_cursor < node_set.length
+              if node_set[scan_cursor].matches?(selector)
+                found_nodes = node_set[cursor..scan_cursor - 1]
+                self.cursor = scan_cursor
+                return found_nodes
+              end
+
+              scan_cursor += 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/parser/markdown/question.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  module Parser
+    module Markdown
+      class Question < Base
+        include Helpers::NodeParser
+
+        # Parse the frontmatter/HTML from the Markdown document and return a Question and its associated Answers
+        def parse
+          Model::Question.new(
+            course_id: frontmatter['course_id'],
+            quiz_id: frontmatter['quiz_id'],
+            id: frontmatter['id'],
+            type: frontmatter['type'],
+            sources: frontmatter['sources'],
+            name: name,
+            description: description,
+            answers: answers,
+            distractors: distractors
+          )
+        end
+
+        private
+
+        # Convert the markdown to HTML for scanning
+        def html
+          @html ||= MarkdownConverter.new(markdown).to_html
+        end
+
+        # Name - contents of first H1
+        def name
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_until('h1').last.content
+        end
+
+        # Description - contents between H1 and first H2
+        def description
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_until('h1')
+          scanner.scan_before('h2').to_html.strip
+        end
+
+        # Each H2 and the content before the next H2 represent an answer
+        def answers
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_before('h2')
+          answers = []
+          while scanner.check('h2')
+            title = scanner.scan('h2').content
+            unless frontmatter['type'] == 'matching_question' && title == 'Incorrect'
+              nodes = scanner.scan_before('h2') || scanner.scan_rest
+              answers << Parser::Markdown::Answer.for(frontmatter['type'], title, nodes)
+            end
+          end
+          answers
+        end
+
+        # Distractors only apply to incorrect answers for the matching_question type
+        def distractors
+          return [] unless frontmatter['type'] == 'matching_question'
+
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_before('h2')
+          while scanner.check('h2')
+            title = scanner.scan('h2').content
+            nodes = scanner.scan_before('h2') || scanner.scan_rest
+            return parse_text_from_nodes(nodes, 'li') if title == 'Incorrect'
+          end
+
+          []
+        end
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/parser/markdown/quiz.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  module Parser
+    module Markdown
+      # Parses a markdown file and returns a Quiz
+      class Quiz < Base
+        include Helpers::NodeParser
+
+        def parse
+          Model::Quiz.new(
+            course_id: frontmatter['course_id'],
+            id: frontmatter['id'],
+            repo: frontmatter['repo'],
+            title: title,
+            description: description
+          )
+        end
+
+        private
+
+        # Convert the markdown to HTML for scanning
+        def html
+          @html ||= MarkdownConverter.new(markdown).to_html
+        end
+
+        # Title - contents of first H1
+        def title
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_until('h1').last.content
+        end
+
+        # Description - rest of document after the first H1
+        def description
+          scanner = Helpers::NodeScanner.new(html)
+          scanner.scan_until('h1')
+          scanner.scan_rest.to_html.strip
+        end
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/repository_interface.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  # Interface for working with a local git repo
+  class RepositoryInterface
+    attr_reader :path, :git
+
+    def initialize(path)
+      path = File.expand_path(path)
+      raise DirectoryNotFoundError unless Pathname(path).directory?
+
+      @path = path
+      @git = Git.init(path)
+    end
+
+    def commit_files(*filepaths, message)
+      relative_paths = filepaths.map { |filepath| relative_path(filepath) }
+      return unless new_repo? || relative_paths.any? { |filepath| pending_changes?(filepath) }
+
+      git.add(relative_paths)
+      git.commit("AUTO: #{message}")
+    end
+
+    private
+
+    def relative_path(filepath)
+      pathname = Pathname(filepath)
+      pathname.relative? ? pathname.to_s : pathname.relative_path_from(path).to_s
+    end
+
+    def pending_changes?(filepath)
+      git.status.untracked?(filepath) || git.status.changed?(filepath) || git.status.added?(filepath)
+    end
+
+    def new_repo?
+      git.log.size.zero?
+    rescue Git::GitExecuteError => e
+      # ruby-git raises an exception when calling git.log.size on a repo with no commits
+      /does not have any commits yet/.match?(e.message)
+    end
+  end
+end

data/lib/github_to_canvas_quiz/reverse_markdown/converters/p.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Override p blocks to enable line wrapping
+# https://github.com/xijo/reverse_markdown/blob/master/lib/reverse_markdown/converters/p.rb
+module ReverseMarkdown
+  module Converters
+    class P < Base
+      def convert(node, state = {})
+        content = treat_children(node, state)
+        "\n\n#{wrap(content).strip}\n\n"
+      end
+
+      private
+
+      def wrap(text, width = 80)
+        text.gsub(/(.{1,#{width}})(\s+|\Z)/, "\\1\n")
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/reverse_markdown/converters/pre.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Override pre blocks to get language using Rouge selector
+# https://github.com/xijo/reverse_markdown/blob/master/lib/reverse_markdown/converters/pre.rb
+module ReverseMarkdown
+  module Converters
+    class Pre < Base
+      def convert(node, state = {})
+        content = treat_children(node, state)
+        if ReverseMarkdown.config.github_flavored
+          "\n```#{language(node)}\n#{content.strip}\n```\n"
+        else
+          "\n\n    #{content.lines.to_a.join('    ')}\n\n"
+        end
+      end
+
+      private
+
+      # Override #treat as proposed in https://github.com/xijo/reverse_markdown/pull/69
+      def treat(node, state)
+        case node.name
+        # preserve newline in <span>, <code> and text blocks
+        when 'text', 'span', 'code'
+          node.text
+        when 'br'
+          "\n"
+        else
+          super
+        end
+      end
+
+      def language(node)
+        lang = language_from_highlight_class(node)
+        lang || language_from_confluence_class(node)
+        lang || language_from_rouge_class(node)
+      end
+
+      def language_from_highlight_class(node)
+        node.parent['class'].to_s[/highlight-([a-zA-Z0-9]+)/, 1]
+      end
+
+      def language_from_confluence_class(node)
+        node['class'].to_s[/brush:\s?(:?.*);/, 1]
+      end
+
+      def language_from_rouge_class(node)
+        node['class'].to_s[/highlight\s(.*)/, 1]
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/reverse_markdown/register.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'converters/p'
+require_relative 'converters/pre'
+
+module ReverseMarkdown
+  Converters.register :p,   Converters::P.new
+  Converters.register :pre, Converters::Pre.new
+end

data/lib/github_to_canvas_quiz/synchronizer/quiz.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  # Markdown => CanvasAPI
+  module Synchronizer
+    # Synchronize a quiz to Canvas based on the contents of a given directory
+    # Given a directory with valid markdown files:
+    #
+    # phase-1-quiz-arrays
+    # |   questions
+    # |   |-- 00.md
+    # |   |-- 01.md
+    # |-- README.md
+    #
+    # Useage:
+    #
+    #   client = CanvasAPI::Client.new(host: host, api_key: api_key)
+    #   Synchronizer::Quiz.new(client, 'phase-1-quiz-arrays')
+    class Quiz
+      attr_reader :client, :path, :repo, :quiz, :questions_with_path
+
+      def initialize(client, path)
+        path = File.expand_path(path)
+        raise DirectoryNotFoundError unless Pathname(path).directory?
+
+        @client = client
+        @path = path
+        @repo = RepositoryInterface.new(path)
+        @quiz = parse_quiz
+        @questions_with_path = parse_questions_with_path
+      end
+
+      def sync
+        backup_canvas_to_json!
+        sync_quiz!
+        sync_questions!
+        backup_canvas_to_json!
+      end
+
+      private
+
+      # Get quiz data from the Markdown file and return a Model::Quiz
+      def parse_quiz
+        raise GithubToCanvasQuiz::FileNotFoundError unless Pathname(quiz_path).exist?
+
+        Parser::Markdown::Quiz.new(quiz_path).parse
+      end
+
+      # Get question data from Markdown files and return a Model::Question along with its path
+      def parse_questions_with_path
+        Dir["#{path}/questions/*.md"].map do |question_path|
+          question = Parser::Markdown::Question.new(File.read(question_path)).parse
+          question.quiz_id = quiz.id
+          question.course_id = quiz.course_id
+          [question, question_path] # need that question path... gotta be a better way!
+        end
+      end
+
+      # create or update quiz on Canvas
+      def sync_quiz!
+        if quiz.id
+          update_quiz!
+        else
+          create_quiz_and_update_frontmatter!
+        end
+      end
+
+      def update_quiz!
+        client.update_quiz(quiz.course_id, quiz.id, { 'quiz' => quiz.to_h })
+      end
+
+      def create_quiz_and_update_frontmatter!
+        canvas_quiz = client.create_quiz(quiz.course_id, { 'quiz' => quiz.to_h })
+        quiz.id = canvas_quiz['id']
+        update_frontmatter(quiz_path, quiz)
+      end
+
+      def quiz_path
+        File.join(path, 'README.md')
+      end
+
+      # Create or update questions on Canvas
+      def sync_questions!
+        questions_with_path.each do |question_with_path|
+          question, path = question_with_path
+          if question.id
+            update_question!(question)
+          else
+            create_question_and_update_frontmatter!(question, path)
+          end
+        end
+        remove_deleted_questions!
+      end
+
+      def create_question_and_update_frontmatter!(question, path)
+        canvas_question = client.create_question(question.course_id, question.quiz_id, { 'question' => question.to_h })
+        question.id = canvas_question['id']
+        update_frontmatter(path, question)
+      end
+
+      def update_question!(question)
+        client.update_question(question.course_id, question.quiz_id, question.id, { 'question' => question.to_h })
+      end
+
+      def remove_deleted_questions!
+        ids = questions_with_path.map { |question_with_path| question_with_path.first.id }
+        client.list_questions(quiz.course_id, quiz.id).each do |canvas_question|
+          id = canvas_question['id']
+          unless ids.include?(id)
+            # delete questions that are no longer present in the repo
+            client.delete_question(quiz.course_id, quiz.id, id)
+          end
+        end
+      end
+
+      def backup_canvas_to_json!
+        quiz_data = client.get_single_quiz(quiz.course_id, quiz.id)
+        questions_data = client.list_questions(quiz.course_id, quiz.id)
+
+        json_data = JSON.pretty_generate({ quiz: quiz_data, questions: questions_data })
+        File.write(json_path, json_data)
+        repo.commit_files(json_path, 'Created Canvas snapshot')
+      end
+
+      def json_path
+        File.join(path, '.canvas-snapshot.json')
+      end
+
+      def update_frontmatter(filepath, markdownable)
+        parsed = FrontMatterParser::Parser.parse_file(filepath)
+        new_markdown = MarkdownBuilder.build do |md|
+          md.frontmatter(markdownable.frontmatter_hash)
+          md.md(parsed.content)
+        end
+        File.write(filepath, new_markdown)
+        repo.commit_files(filepath, 'Updated frontmatter')
+      end
+    end
+  end
+end

data/lib/github_to_canvas_quiz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GithubToCanvasQuiz
+  VERSION = '0.1.0'
+end

data/lib/github_to_canvas_quiz.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'front_matter_parser'
+require 'git'
+require 'htmlentities'
+require 'json'
+require 'nokogiri'
+require 'redcarpet'
+require 'rest-client'
+require 'reverse_markdown'
+require 'rouge'
+require 'rouge/plugins/redcarpet'
+require 'thor'
+require 'yaml'
+
+require 'github_to_canvas_quiz/builder/quiz'
+
+require 'github_to_canvas_quiz/canvas_api/endpoints/quizzes'
+require 'github_to_canvas_quiz/canvas_api/endpoints/quiz_questions'
+require 'github_to_canvas_quiz/canvas_api/endpoints'
+require 'github_to_canvas_quiz/canvas_api/client'
+
+require 'github_to_canvas_quiz/model/answer/fill_in_multiple_blanks'
+require 'github_to_canvas_quiz/model/answer/matching'
+require 'github_to_canvas_quiz/model/answer/multiple_answers'
+require 'github_to_canvas_quiz/model/answer/multiple_choice'
+require 'github_to_canvas_quiz/model/answer/multiple_dropdowns'
+require 'github_to_canvas_quiz/model/answer/short_answer'
+require 'github_to_canvas_quiz/model/answer/true_false'
+require 'github_to_canvas_quiz/model/quiz'
+require 'github_to_canvas_quiz/model/question'
+
+require 'github_to_canvas_quiz/parser/canvas/helpers'
+require 'github_to_canvas_quiz/parser/canvas/answer'
+require 'github_to_canvas_quiz/parser/canvas/question'
+require 'github_to_canvas_quiz/parser/canvas/quiz'
+require 'github_to_canvas_quiz/parser/markdown/helpers/node_parser'
+require 'github_to_canvas_quiz/parser/markdown/helpers/node_scanner'
+require 'github_to_canvas_quiz/parser/markdown/answer'
+require 'github_to_canvas_quiz/parser/markdown/base'
+require 'github_to_canvas_quiz/parser/markdown/question'
+require 'github_to_canvas_quiz/parser/markdown/quiz'
+
+require 'github_to_canvas_quiz/reverse_markdown/register'
+
+require 'github_to_canvas_quiz/synchronizer/quiz'
+
+require 'github_to_canvas_quiz/cli'
+require 'github_to_canvas_quiz/markdown_builder'
+require 'github_to_canvas_quiz/markdown_converter'
+require 'github_to_canvas_quiz/repository_interface'
+require 'github_to_canvas_quiz/version'
+
+module GithubToCanvasQuiz
+  class UnknownQuestionType < StandardError; end
+
+  class FileNotFoundError < StandardError; end
+
+  class DirectoryNotFoundError < StandardError; end
+
+  class Error < StandardError; end
+end