tech_debt.md

Smartdown/smart-answers tech-debt and potential improvements

Testing and confidence

• Enforce unique flow name between Smartdown/SA
• Smartdown lint/validate
  • Check all ref'd nodes exist
  • Check no orphan nodes
  • Run in SA CI
• Smartdown Scenarios
  • Feature flag to disable artefact lookup

Smart Answer features

• Deprecate hint
• Remove has_foo? methods
• Remove subtitle field
• Allow both prefix and suffix labels
  • Check if this is an acessability issue

Documentation

• Smartdown readme
• How to do a transition
• Language feature guide (not as a readme)
• General architecture, layers
• Glossary: flow, node, element, predicate, state, evaluation

Misc

• Otherwise predicate in graph not useful
• should be NOT(previous branch)?

Smart Answer app

• Adaptors
  • Group presenters in adaptor module
  • distinct from other libs
  • Inefficient building of smartdown modules - all "extendables" are shoved inside modules for every flow, regardless if used.
• Put smart_answer presenters in module to avoid name clash
  • Rename smartdown adapt[o|e]r
  • Lack of testing
    • create minimal test harnesses as a start
• Pass artefact into controllers
• Response naming/handling
  • smart answer vs smartdown
  • multiple questions per page vs single
  • checkbox multi response
• lots of contoller/logic duplication for SA/Smartdown
• namespace smart_answer rake tasks, to avoid confusion
• Tests running incredibly slowly
• use human names in graph
• multiple folders for plugins: keep or change?

Smartdown

• Naming
  • Predicates, vs nodes, vs elements
  • Non predicate constructs, conditional, interpolation
  • should identifier parse definition include ?
    • confusing named predicate (which is bool)
    • vs name of a state var, eg question_1?
  • too many things called state
  • flow input, directory input, input set - wat?
• Predicates
  • clarify naming of predicates
  • split predicates vs language models
  • predicates as booleans/operators
  • distinguish functions
  • scope predicates to Rules only
  • add variable 'predicate', evaluate to state var
  • OR predicate
  • Useful for simplifying some SPL node rules
• Testing
  • Lack of acceptance tests
• Move conditional evaluation into model
  • Simplify/replace resolver
• Make nodes evaluate(state)able? eg
  • node.evaluate(state) resolves conditionals, interpolations, etc
  • Could replace NodePresenter
• Abstraction
  • Push element parsing into models/node transform as much as possible
  • Go through API models and enumerate direct element use
• Read/understandability
  • Overly complex interpolation class
• Potential bugs
  • Test nested function parsing, not just calling
• Answer object: use of to_s, humanize, value is odd and inconsistent:
  • stop using forwardable approach
  • explicitly document what to_s, humanize, value (what is for URLs/representation in outcomes, smartdown response input etc...)
• Monkey-patching comment in Smartdown: improve comment and open a possible parslet issue

Smartdown API

• DirInput / FileInput, expects .read
• Push Element filtering examples from API into Model layer
  • even better, in to transform, super simple structs
• Smartdown shouln’t take y for started, ui concern
• Flow naming convention, Gem assumes cover sheet, App dir
• Better directory structure
  • distinguish Node > Element
• Review API models and restrict to core responsibilities
  • Could they be re-written as structs?
• Plugins
  • one file per question
  • stop using class methods for everything
  • distinguish run-time vs build time by which methods take arguments
  • judicious memoization during initialization of each plugin set
• Distinction between country questions/multiple choice questions: could we make country questions more generic?

Smart Answer transition

• calendar support(?)
• tool to convert rb/yml flows to smartdown
• tool to convert rb/yml tests to scenarios
• support all question types
  • money
  • checkbox
  • date of birth
• custom validation: custom date ranges?

Check if this is fixed

• Handle missing need_id in Smartdown, don't raise error