bisectly arch overview

gistfile1.txt

Bisectly Architecture Overview
------------------------------

Components
~~~~~~~~~~

* bin/bisectly
* lib/bisectly/bsfl.rb
* lib/bisectly/clients/vim.rb
* lib/bisectly/thumpers/file_thumper.rb

.synopsis:

  bisectly CLIENT TEST-FILE

Test File
~~~~~~~~~

* The test file is passed to the client and executed by the CLIENT.
* The return value determines pass/fail for the current bundle
  configuration.
* Because this file is executed by the CLIENT, its type is client
  dependent - it might be a simple shell script or a viml script or
  ...

Client
~~~~~~

* The client is a domain handler for its corresponding system/command
  and is responsible for:
  1. setting up a playground (e.g. cp -a ~/.vim/ /tmp/bisectly/001/)
  2. collecting domain-specific 'bundles' (e.g. .../bundle/*)
     * identifying dependencies within bundle associations (e.g. in
       vim, vim-buffalo depends on Vimpeg, so you can't remove vimpeg
       without also removing vim-buffalo)
     * identifying (or accepting from the user) 'pinned on/off'
       bundles that will always be enabled/disabled respectively
       throughout the tests
     * presenting the 'unpinned' modules to the BSFL engine for
       binary juggling
  3. accepting 'enable' and 'disable' instructions from the BSFL
     engine as it partitions the 'unpinned' bundles and...
  4. accepting 'test' instruction from BSFL engine and reporting
     corresponding test/fail response.

BSFL Engine
~~~~~~~~~~~

* The core binary search fault localisation code that tracks its own
  bundle state and calls through to the provided CLIENT for enable,
  disable and test functionality.

Rough Pseudocode:
^^^^^^^^^^^^^^^^^

  # init
  @client = ARGV[0]   # not exactly, but semantically
  @client.initialize_playground(maybe some args)

  @client.register_test(ARGV[1])

  @enabled = @client.get_bundles()
  @disabled = []
  
  # confirm that the test fails with all enabled plugins loaded
  @client.enable(@enabled)
  assert false, @client.test()
  
  # confirm that the test passes with all enabled plugins disabled if
  # a test depends on certain plugins being enabled/disabled, they can
  # be pinned on or off accordingly
  @client.disable(@enabled)
  assert true, @client.test()

  # prime bisection lists
  (@enabled, @disabled) = (left half of enabled, right half of enabled)

  found = false
  while not found
    @client.enable(@enabled)
    @client.disable(@disabled)
    state = @client.test()
    if state == true # test passed, so 'failing' plugin is in 'disabled' list
      if @disabled.count > 1
        (@enabled, @disabled) = (left half of disabled, right half of disabled)
      else
        found = true
      endif
    else # test failed, so 'failing' plugin is in 'enabled' list
      if @enabled.count > 1
        (@enabled, @disabled) = (left half of enabled, right half of enabled)
      else
        @disabled = @enabled
        found = true
      endif
    endif
  endwhile


Thumpers
~~~~~~~~

(yes, i need a better name for these)

* Handle the actual file-system/network/mindreading processing
  necessary to do the 'enable', 'disable' and *maybe* 'test'
  instructions depending on the nature of the backend. For vim, this
  will simply be Ruby Filesystem operations. For git it will be
  through a git command process interaction; for mysql something
  similar; for a network service, it might require rest-ful
  interaction through curl or some other gafuffle.

Example Invocation
~~~~~~~~~~~~~~~~~~

bisectly vim f-jumps-over-lines.vim

.where f-jumps-over-lines.vim is:
=================================
  enew
  append
  this is
  a test
  .
  
  normal 1G0|fa
  
  if getpos('.')[1] == 1
    quit!
  else
    cquit!
  endif
=================================

And the resulting output from bisectly would be:

bundles/vim-fanfingtastic