marko 0.1.0 → 0.4.0

data/lib/assets/demo/src/fr/markup.md

@@ -1,111 +0,0 @@
-# Source Markup
-{{id: .markup, parent: fr}}
-
-The main and only entity in the system is [[fr.treenode]]. The system shall provide the following abilities for the entity:
-
-@@list
-
-## Node Markup
-{{id: .node}}
-
-The system shall support the following node markup.
-
-```markdown
-# <title>
-{{\<meta\>}}
-\<body\>
-```
-
-Where:  
-
-- Each node starts from Markdown header mark `#`.
-- The header mark can be followed by node title.
-- The next line _might_ contain metadata block:
-   - that starts from `{{` and finishes with `}}`;
-   - that can be one or multiline string.
-- The next lines tile the end of file or next header mark `#` are considered as node body.
-
-## Get Sources
-
-The system shall provide function to getting all sources files from project repository.
-
-@@todo define project repository
-
-## Parse Source
-
-The system shall provide the function to parse source file.
-
-During the parsing process the system must record source information within the node parsed, such as origin file name and the number of line inside the origin where the node begins. This information must be stored inside metadata as [[fr.treenode.orig]].
-
-__Input__
-
-Parameter Type   0..* Description
---------- ------ ---- -----------
-filename  String 1    filename
-
-__Output__
-
-Parameter Type   0..* Description
---------- ------ ---- -----------
-node      Node   0..n node parsed
-
-## Assemble Tree
-
-The system shall provide the function to assemble the artifact tree. The artifact tree is assembled based on [[fr.treenode.tree]].
-
-@@todo The assemblage algorithm, errors handler
-
-__Input__
-
-Parameter Type   0..* Description
---------- ------ ---- -----------
-node      Node   0..n node array
-
-__Output__
-
-Parameter Type   0..* Description
---------- ------ ---- -----------
-node      Node   1    root tree
-
-## Inject Id
-
-The system shall provide each node with unique node Id.
-
-Some nodes can already have ids from source file, especially those that referenced as parent or child and placed in separate files. For those nodes that still have empty id, the system must generate auto id 0..99.
-
-For example, when the system has assembled the tree
-
-```markdown
-# Artifact
-## Introduction
-### Purpose
-### Scope
-# User Requirements #ur
-# Functional Requirements #fr
-```
-
-and then generated id, the generated ids should be as follows:
-
-```markdown
-# Artifact Title #00
-## Introduction #01.01
-### Purpose #01.01.01
-### Scope #01.01.02
-# User Requirements #ur
-# Functional Requirements #fr
-```
-
-__Input__
-
-Parameter Type   0..* Description
---------- ------ ---- -----------
-root      Node   1    root node
-
-## Checking Tree
-
-The system shall provide the function to check assembled tree for errors related to assembling tree based on [[fr.treenode.tree]]. The system must check the following errors:
-
-- `duplicate id`, finds two or more nodes that share the same id;
-- `unknown parent`, finds nodes that have `parent` metadata, but parent not found in the tree;
-- `unknown index`, finds nodes with `order_index` metadata where one or more children in the index not found;
-- `unknown links`, finds nodes containing links but the links are not found.

data/lib/assets/demo/src/fr/storage.md

@@ -1,16 +0,0 @@
-# Sources Storage
-{{id: .storage, parent: fr}}
-
-The system shall provide a storage for artifact sources. The storage must provide the following features:
-
-- Create a new project
-- Remove project
-- Get the list of project sources
-- Get project source
-
-@@skip
-
-At this stage only option will be developed - the filesystem storage. Other options that should be considered for future stages are
-
-- Database storage (SQL and NoSQL)
-- Confluence Wiki

data/lib/assets/demo/src/fr/treenode.md

@@ -1,34 +0,0 @@
-# TreeNode
-{{id: .treenode, parent: fr}}
-
-The system shall provide `Node` entity with the following properties that provide the following attributes:
-
-Property  Type   *..n Default Description
---------- ------ ---- ------- -----------
-id        String 1    ""      Node identifier
-parent    Node   1    null    Parent node reference
-title     String 1    ""      Node title
-meta      Hash   1    {}      Node metadata
-body      String 1    ""      Node body
-items     Node   0..n []      Child node reference
-
-## Tree Metadata
-{{id: .tree}}
-
-To assemble the project artifact from nodes placed among several source files, the system shall provide the following optional tree metadata attributes:
-
-Attribute   Type   0..n Description
------------ ------ ---- --------------
-id          String 0..1 Unique node id
-parent      String 0..1 Parent id
-order_index String 0..1 Children ids delimited by space
-
-## Source Metadata
-{{id: .orig}}
-
-During source file parsing, the system must store the following node origin information:
-
-Attribute   Type   0..n Description
------------ ------ ---- --------------
-origin      String 1    Source filename
-lineno      String 1    Number of line

data/lib/assets/demo/src/index.md

@@ -1,34 +0,0 @@
-# Intro
-{{id: intro}}
-
-# Users
-{{id: usr}}
-
-The users of the system are different people who play for authoring various sorts of technical documentation. It might be a technical writer, business/systems analyst, developer, etc.
-
-# User Requirements
-{{id: ur, order_index: uc}}
-
-## Use Cases
-{{id: uc, order_index: .create.project .general.flow}}
-
-# Functional Requirements
-{{id: fr, order_index: .treenode .markup .storage .assemble .compile}}
-
-# Interface Requirements
-{{id: ui, order_index: .cli .gem}}
-
-# Assumptions and Dependencies
-{{id: as}}
-
-##
-
-The system requires a user interface for managing markup sources. It is assumed that users utilize any text editor of their choice.
-
-##
-
-The system requires tools for collaboration on artifacts by several authors simultaneously. Because of the plain text nature of the markup sources, It is assumed using Git for managing the artifact sources repository.
-
-##
-
-The system requires the compilation of artifacts into deliverables in form of well-supported formats like pdf, doc, etc. It is assumed using Pandoc for creating deliverables.

data/lib/assets/demo/src/intro.md

@@ -1,98 +0,0 @@
-# Purpose
-{{parent: intro}}
-
-The main purpose of this document is to provide a comprehensive demo project for Marko gem. The other technical purpose is to have Marko Sandbox for testing and development.
-
-# Problem
-{{parent: intro}}
-
-There are a few alternatives for authors who work on bulky software artifacts like requirements specification. They can apply one of the following tools
-
-@@todo find a few popular requirements management tools
-@@todo find a few popular Tex alternatives
-
-- a particular requirements management tool, like Doors
-- a Word Processor, like Microsoft Word, Libra Office, or Google Docs;
-- an elaborate publishing system, like Tex;
-- or just using a simple Wiki system, like Confluence or Redmine.
-
-A requirements management tool might seem to be the best choice there because it is tailored exactly for the required process. But it certainly will be a "hard way" from a cost and time perspective, an elaborate and expensive solution requiring personnel to be trained and vendor support.
-
-Although deliverable artifacts could be seen as a usual document structured and expressed in headers and paragraphs, the meaning of each of those can be different. So word processors and wiki systems might be the perfect choice for presenting artifact deliverables, but they lack of semantic fails for content development and management. The best of them provide a scripting language for document processing, but it is usually too complicated and again lacks particular entities' semantics (stakeholders, requirements, constraints, etc.)
-
-Designing documents of hundreds of pages in word processors brings some peculiar drawbacks. The software tends to become "bulky" in operating, consuming too many system resources and responding with delays; tend to be fragile with styles.
-
-__The problem of__ the lack of simple tools and approaches for writing software artifacts __affects__ technical writers who develop and manage the artifacts __the impact of which is__ they tend to choose a publishing tool or a word processor that does not fit well to work on software artifacts causing lots of manual work and maybe other confusing things like "bulky" documents __a successful solution would be__ the tool that will provide
-
-- a plain text markup for writing artifact items, that will be easy to read for humans, and processed by machines;  
-- a "semantics" layer to distinguish artifact items (actors, requirements, etc.) from supported text
-- the ability to automate tasks based on processing content according to its semantic value;
-- the ability to build a convenient presentation of the artifact (pdf, doc, odt);
-- will not depend on OS platform and any proprietary format or software.
-
-@@skip
-
-It provides a statement summarizing the problem being solved by the project.
-
-__The problem of__ [describe the problem]
-__affects__ [the stakeholders affected by the problem]
-__the impact of which is__ [what is the impact of the problem?]
-__a successful solution would be__ [list some key benefits of a successful solution]
-
-# Product
-{{parent: intro}}
-
-@@todo redesign the product statement for "who" section
-
-__For__ authors of software artifacts __who__ need a reliable and repeatable process of managing big software artifacts __the__ Marko Markup Compiler is a free open source software __that__ brings a "docs-as-code" approach with efficient plain markup for artifact sources, @@todo templates, CLI, Rake ..
-
-@@skip
-
-__For__ [target customer]
-__Who__ [statement of the need or opportunity]
-__The__ [product name] is a [product category]
-__That__ [key benefit, compelling reason to buy]
-__Unlike__ [primary competitive alternative]
-__Our product__ [statement of primary differentiation]
-
-# Scope
-{{parent: intro}}
-
-The developing system will consist of
-
-- the simple plain markup for writing the artifact sources;
-- the repository of artifact sources;
-- the algorithm for assembling the artifact from sources;
-- the markup for templates for publishing the artifact;
-- the command line interface for compiling the artifact into deliverables based on the templates  
-- the Ruby Gem that presents the artifact as the collection o items that can be easily visited for tasks automation;
-- the demo project that will help the customers to adopt the approach and design their own solutions based on the approach.
-
-# Definitions
-{{parent: intro}}
-
-CLI
-
-:   Command-line interface
-
-ERB
-
-:   Ruby Templating system
-
-# References
-{{parent: intro}}
-
-1. [Markdown Guide](https://www.markdownguide.org/)
-2. [Pandoc User's Guide](https://pandoc.org/MANUAL.html)
-3. [Git User's Manual](https://git-scm.com/docs/user-manual.html)
-
-# Overview
-{{parent: intro}}
-
-The remaining sections of this document provide user- and functional requirements of the system.
-
-The [[usr]] chapter introduces users of the system.
-
-The next chapter [[ur]] introduces users requirements that establish the context for the functional requirements.
-
-The following chapter [[fr]] describes detailed requirements for functions and user interfaces.

data/lib/assets/demo/src/ui/cli.md

@@ -1,26 +0,0 @@
-# Command-line interface
-{{id: .cli, parent: ui}}
-
-The system shall provide a command-line interface. The interface must provide the following commands:
-
-@@list
-
-## Create a new project
-
-The system shall provide the `new PROJECT` command. When the user requests the `new PROJECT` command, the system
-
-- ensures that `PROJECT` folder does not exist or fails
-- creates `PROJECT` folder and copies required files for new project
-- reports the user about success  
-
-## Compile artifact
-
-The system shall provide the `compile [-t TEMPALTE] [-o FILENAME]` command. When the user requests the `compile` command, the system
-
-- ensures that current directory is `Marko Project` directory, or fails
-- load `template`,
-  - load from the `TEMPLATE` parameter when provided
-  - or load default template when not
-- creates `tree` by using [[fr.assemble]]
-- compiles the tree by [[fr.compile]].(`tree`, `template`, `filename`)
-- reports the user about success

data/lib/assets/demo/src/ui/gem.md

@@ -1,14 +0,0 @@
-# Gem interface
-{{id: .gem, parent: ui}}
-
-The system shall provide Ruby Gem with the following functions
-
-@@list
-
-## Marko.assemble
-
-@@todo define Marko.assemble
-
-## Marko.compile
-
-@@todo define Marko.compile

data/lib/assets/demo/src/ur/uc.create.project.md

@@ -1,8 +0,0 @@
-# Create a new project
-{{id: uc.create.project, parent: uc}}
-
-__Main Flow__
-
-1. The user requests the system to create a new project passing a project folder for new project.
-2. The system checks for project folder to be unique. When  folder with the same name exists already, the system reports it to the user and the scenario is finished.
-3. The system creates the project folder and furnish it with project structure.

data/lib/assets/demo/src/ur/uc.general.flow.md

@@ -1,14 +0,0 @@
-# General Clerq flow
-{{id: uc.general.flow, parent: uc}}
-
-__Prerequisites__
-
-1. The user inside Marko project (see [[uc.create.project]])
-
-__Main Flow__
-
-1. The user creates and makes changes to the sources of the project. [outside the system]
-2. The user requests the system to `compile` the artifact.
-3. The system assembles the artifact from source files.
-4. The system checks the artifact and reports the errors to the user if any.
-5. The system returns the assembled artifact.

data/lib/assets/init/README.md

@@ -1,61 +0,0 @@
-% Marko Demo Project
-
-Welcome to your new [Marko](https://github.com/nvoynov/clerq) project!
-
-# Structure
-
-This project has the following structure:
-
-- [bin/](bin/) - output folder
-- [bin/assets/](bin/assets/) - assets folder
-- [src/](src/) - markup sources
-- [tt/](tt/) - templates
-- [marko.yml](marko.yml) - project configuration
-- [Rakefile](Rakefile) - Rakefile
-- [README.md](README.md)
-
-# Interface
-
-Run `marko` command in your console to see basic command-line interface.
-
-Extend it yourself through Rakefile
-
-# Git Repository
-
-[Git How To](https://githowto.com/)
-
-Incorporates changes from a remote repository:
-
-    git pull
-
-Create a new branch to start any activity with the repository:
-
-    git branch <branch_name>
-
-Make changes and commit your work:
-
-    git add .
-    git commit -m "branch_name - commit description"
-
-When your changes finished, incorporate changes from the remote repository and merge the `master` branch to your `branch_name`:
-
-    git checkout master
-    git pull
-    git checkout <branch_name>
-    git merge master
-
-Resolve all conflicts and commit changes:
-
-    git add .
-    git commit -m "branch_name conflicts resolved"
-
-Merge your changes to the `master` branch:
-
-    git checkout master
-    git merge <branch_name>
-
-Push your changes to the remote repository:
-
-    git push
-
-Create a merge request if you are not allowed to push to the `master` branch.

data/lib/assets/init/Rakefile

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-require 'marko'
-require 'marko/markup'
-
-namespace :marko do
-
-  # @todo pandoc: bin/arfifact.docx: openBinaryFile: permission denied (Permission denied)
-  #   Success! Find the artifact in bin/arfifact.docx
-  #
-  desc 'Publish the artifact'
-  task :publish do
-    output = 'bin/arfifact'
-    `marko c -o #{output}.md`
-    pandoc = `pandoc #{output}.md -o #{output}.docx`
-    File.delete("#{output}.md")
-    puts "Success! Find the artifact in #{output}.docx"
-  end
-
-  desc 'Print table of contents'
-  task :toc, :query do |t, args|
-    args.with_defaults(query: '')
-    tree = Marko.assemble
-    query = args.query
-    unless query.empty?
-      tree = tree.find_node(query)
-      unless tree
-        puts "Nothing to be printed!"
-        return
-      end
-      tree.orphan!
-    end
-    tree.each do |n|
-      if n.root?
-        puts "% #{n.title}" if n.root?
-        next
-      end
-      title = n.title.empty? ? n.id : n.title
-      puts '#' * n.nesting_level + " #{title} ##{n.id}"
-    end
-  end
-
-  desc 'Print @@todo'
-  task :todo do
-    tree = Marko.assemble
-    tree.to_a.drop(1)
-      .select{|n| n.body =~ /@@todo/}
-      .each{|n|
-        list = n.body
-          .scan(/@@todo.*$/)
-          .map{_1.sub(/@@todo/, '')}
-          .map{"  #{_1.strip}"}
-          .join(?\n)
-        puts n[:origin]
-        puts list
-        puts
-      }
-  end
-
-  def datestamp
-    Time.new.strftime('%Y%m%d')
-  end
-
-  def timestamp
-    Time.new.to_s
-  end
-
-  desc 'Punch meeting munutes'
-  task :mm, :extra do |t, args|
-    args.with_defaults(extra: '')
-    extra = args.extra
-    Dir.mkdir('mm') unless Dir.exist?('mm')
-    body = MINUTES % timestamp
-    name = "minutes-#{datestamp}#{extra.empty? ? '' : ?_ + extra}"
-    name = File.join('mm', name)
-    errm = "Minutes exists already. Maybe you can provide [EXTRA]?"
-    fail errm if File.exist?(name)
-    File.write(name, body)
-  end
-
-  MINUTES = <<~EOF.freeze
-    %% Meeting Minutes %s
-
-    # Attendants
-
-    1.
-    2.
-
-    # Questions
-
-    1.
-    2.
-
-    # Decisions
-
-    1.
-    2.
-  EOF
-
-end

data/lib/assets/init/tt/artifact.md.tt

@@ -1,3 +0,0 @@
-<%= @node.header %>
-<%= @node.meta   %>
-<%= @node.body   %>

data/lib/marko/artifact.rb

@@ -1,3 +0,0 @@
-module Marko
-  Artifact = Struct.new(:id, :title, :template, :filename)
-end

data/lib/marko/assembler.rb

@@ -1,82 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "gadgets"
-require_relative "config"
-require_relative "loader"
-require_relative "tree_node"
-
-module Marko
-
-  # The strategy for assembling sources into artifact tree
-  class Assembler < Service
-
-    class Failure # < StandardError
-      attr_reader :errors
-      def initialize(message, *errors)
-        @errors = errors
-        super(
-          errors
-            .map{|e| e.lines.map{|l| "  #{l}"}.join }
-            .unshift(message + ?\n)
-            .join
-        )
-      end
-    end
-
-    # @return [TreeNode]
-    def call
-      @block.(:stage, 'loading sources') if @block
-      buffer, errors = Loader.(&@block)
-      fail Failure.new('markup parsing errors', *errors) if errors.any?
-      @block.(:stage, 'tree assemblage') if @block
-      tree = assemble(buffer)
-      @block.(:stage, 'tree enrichment') if @block
-      injectid(tree)
-      @block.(:stage, 'tree validation') if @block
-      errors = validate(tree)
-      fail Failure.new('tree validation errors', *errors) if errors.any?
-      tree
-    end
-
-    protected
-
-    # @param buff [Array<TreeNode>]
-    # @return [TreeNode]
-    def assemble(buff)
-      art = Marko.artifact
-      TreeNode.new(art.title, id: '0').tap {|root|
-        # @todo buff.inject(root, :<<) wrong but why?
-        buff.each{|n| root << n}
-        root.items
-          .select{|node| node[:parent] && node[:parent] != node.parent_id}
-          .each{|node|
-            parent = root.find{|n| n.id == node[:parent]}
-            next unless parent # is must be left under root
-            parent << node
-            node.delete_meta(:parent)
-            root.delete_item(node)
-          }
-      }
-    end
-
-    def injectid(tree)
-      counter = {}
-      tree
-        .select {|node| node.id.empty?}
-        .each do |node|
-          index = counter[node.parent] || 1
-          counter[node.parent] = index + 1
-          id = index.to_s.rjust(2, '0')
-          id = '.' + id unless node.parent == tree
-          node[:id] = id
-        end
-    end
-
-    def validate(tree)
-      validator = ValidatorPlug.plugged
-      validator.(tree)
-    end
-
-  end
-
-end

data/lib/marko/compiler.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "tree_node"
-require_relative "gadgets"
-
-module Marko
-  class Compiler
-    extend Pluggable
-    def call(tree, template, filename, &block)
-      @tree = MustbeTreeNode.(tree)
-      @template = MustbeString.(template)
-      @filename = MustbeString.(filename)
-      @block = block
-    end
-  end
-end

data/lib/marko/gadgets/pluggable.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Marko
-  # Pluggable mixin serves for dependency injection
-  #
-  # @example
-  #   class Storage
-  #     extend Pluggable
-  #     def call
-  #     end
-  #   end
-  #
-  #   StoragePort = Storage.port
-  #
-  #   class SequelStorage < Storage
-  #   end
-  #
-  #   StoragePort.plugged = SequelStorage.new
-  #
-  #   require 'forwardable'
-  #   class Service
-  #     extend Forwardable
-  #     def_delegator :StoragePort, :plugged, :storage
-  #     def call
-  #       storage.call
-  #     end
-  #   end
-  module Pluggable
-
-    def plug
-      klass = self
-      Module.new {
-        extend Plug;
-        plug klass
-      }
-    end
-
-    module Plug
-      def plug(klass)
-        @klass = klass
-      end
-
-      def plugged
-        fail "unknown @klass" unless @klass
-        @plugged ||= @klass.new
-      end
-
-      def plugged=(obj)
-        fail ArgumentError.new("required an instance of #{@klass}"
-        ) unless obj.is_a?(@klass)
-        @plugged = obj
-      end
-    end
-  end
-end