clerq 0.1.0 → 0.3.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (69) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +4 -3
  3. data/CHANGELOG.md +49 -0
  4. data/Gemfile.lock +9 -9
  5. data/README.md +260 -133
  6. data/Rakefile +1 -0
  7. data/clerq.gemspec +6 -6
  8. data/clerq.thor +28 -0
  9. data/docs/README.md +408 -0
  10. data/lib/assets/knb/SRS-IEEE-830-1998.md +293 -0
  11. data/lib/assets/knb/SRS-RUP.md +283 -0
  12. data/lib/assets/knb/business-case.md +135 -0
  13. data/lib/assets/knb/ears-with-examples.md +101 -0
  14. data/lib/assets/knb/problem-statement.md +8 -0
  15. data/lib/assets/knb/product-statement.md +8 -0
  16. data/lib/assets/knb/requirement-attributes.md +26 -0
  17. data/lib/assets/knb/requirement-classification.md +27 -0
  18. data/lib/assets/knb/requirement-life-cycle.md +47 -0
  19. data/lib/assets/knb/requirement-quality.md +13 -0
  20. data/lib/assets/knb/use-case.md +39 -0
  21. data/lib/assets/knb/vision-document.md +191 -0
  22. data/lib/assets/lib/clerq_doc.thor +119 -0
  23. data/lib/assets/lib/colonize_repo.rb +82 -0
  24. data/lib/assets/lib/spec/colonize_repo_spec.rb +85 -0
  25. data/lib/assets/new/clerq.thor.tt +32 -5
  26. data/lib/assets/new/content.md.tt +3 -40
  27. data/lib/assets/tt/default.md.erb +23 -42
  28. data/lib/assets/tt/pandoc.md.erb +11 -8
  29. data/lib/clerq.rb +57 -12
  30. data/lib/clerq/cli.rb +77 -60
  31. data/lib/clerq/entities.rb +0 -1
  32. data/lib/clerq/entities/node.rb +135 -115
  33. data/lib/clerq/properties.rb +1 -3
  34. data/lib/clerq/repositories.rb +2 -4
  35. data/lib/clerq/repositories/file_repository.rb +59 -0
  36. data/lib/clerq/repositories/node_repository.rb +72 -30
  37. data/lib/clerq/repositories/text_repository.rb +47 -0
  38. data/lib/clerq/services.rb +8 -0
  39. data/lib/clerq/services/check_assembly.rb +108 -0
  40. data/lib/clerq/{interactors → services}/create_node.rb +12 -11
  41. data/lib/clerq/services/load_assembly.rb +54 -0
  42. data/lib/clerq/services/query_node.rb +72 -0
  43. data/lib/clerq/services/query_template.rb +26 -0
  44. data/lib/clerq/services/read_node.rb +101 -0
  45. data/lib/clerq/services/render_erb.rb +29 -0
  46. data/lib/clerq/services/render_node.rb +37 -0
  47. data/lib/clerq/services/service.rb +19 -0
  48. data/lib/clerq/settings.rb +2 -2
  49. data/lib/clerq/version.rb +1 -1
  50. metadata +49 -37
  51. data/TODO.md +0 -3
  52. data/lib/assets/tt/gitlab.md.erb +0 -93
  53. data/lib/assets/tt/raw.md.erb +0 -23
  54. data/lib/clerq/entities/template.rb +0 -19
  55. data/lib/clerq/gateways.rb +0 -3
  56. data/lib/clerq/gateways/gateway.rb +0 -17
  57. data/lib/clerq/gateways/in_files.rb +0 -36
  58. data/lib/clerq/gateways/in_memory.rb +0 -35
  59. data/lib/clerq/interactors.rb +0 -5
  60. data/lib/clerq/interactors/check_nodes.rb +0 -81
  61. data/lib/clerq/interactors/compile_nodes.rb +0 -31
  62. data/lib/clerq/interactors/interactor.rb +0 -28
  63. data/lib/clerq/interactors/join_nodes.rb +0 -59
  64. data/lib/clerq/interactors/query_nodes.rb +0 -62
  65. data/lib/clerq/repositories/in_memory.rb +0 -45
  66. data/lib/clerq/repositories/node_reader.rb +0 -107
  67. data/lib/clerq/repositories/repository.rb +0 -11
  68. data/lib/clerq/repositories/template_repository.rb +0 -53
  69. data/lib/clerq/templater.rb +0 -32
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d95f522537af88379a6881b154fc50453973102601db1cb4be573f655a33a78d
4
- data.tar.gz: cb5e26ff19ff66d0ecc6364decb2caaee046c763956fdd2c39b9e71e932c6abb
3
+ metadata.gz: 5b4f176e14fda651b8525a736fa58e13067aa7fe1921c654b42f846c0fd16db3
4
+ data.tar.gz: 1da7ae883db48480c39329da9edd22be59497084f5dc9f7d94b202a0787df787
5
5
  SHA512:
6
- metadata.gz: 2ce20279f674973d75ab59d1cdaf474248459a442dd58eeebb9980c1d59fe4c687c7956e72bade7be78b9b5134b595e35e3859d5a983cb009afcb17481a47ff5
7
- data.tar.gz: 55b67ea4ef4b43285c6c5eb51b49d2c3fb2cdef7f323dfe897a4e8a9ecd5644d3b6b3ee563ab78bc06291a2cdc9a3b6ed9e2bcc784669bc842438ac0f96a42b1
6
+ metadata.gz: a860df3d47d44149ceb5794d1c80b8ca850311c02d73177492538eb354b455bd4aecdec0a2217972a21613919c33ca3967c9d95bfb3eaf80517df5b138656e32
7
+ data.tar.gz: 6350de56e1620422880c76ce19d9daea6c0bc9549edb1719eee3c8ef7bb2453b063852489698464fd2049e1f11e2845b0d0f1b77319f91f9179a6353f962bd62
data/.gitignore CHANGED
@@ -1,5 +1,4 @@
1
1
  /lib/sandbox/
2
- /test/.sandbox/
3
2
  /.imdone/
4
3
  /.bundle/
5
4
  /.yardoc
@@ -8,5 +7,7 @@
8
7
  /doc/
9
8
  /pkg/
10
9
  /spec/reports/
11
- /test/tmp/
12
- /tmp/
10
+ /docs/.*
11
+ /docs/_*
12
+ /docs/Gemfile*
13
+ TODO.md
data/CHANGELOG.md ADDED
@@ -0,0 +1,49 @@
1
+ # Change log
2
+
3
+ ## 0.3.3 (2021-07-05)
4
+
5
+ * Updated keyword argument in Service class to support Ruby 3. If you need Ruby 2.X support, you should use v0.3.2.
6
+ * Updated `minitest`, `bundler` and `thor` dependencies.
7
+ * Improved `default.md.erb` and `pandoc.md.erb` - now it adds automatic title `.id` when original title is empty.
8
+
9
+ ## 0.3.2 (2020-07-05)
10
+
11
+ * Updated `rake`, `bundler`, and `thor` dependencies.
12
+
13
+ ## 0.3.1 (2019-12-13)
14
+
15
+ * Fixed error with reading files that read attributes to body.
16
+ * Added `mm` command to `<project>.thor` that creates "Meeting Minutes" files in `<project>/mm` folder.
17
+
18
+ ## 0.3.0 (2019-12-04)
19
+
20
+ * Meet services instead of interactors. All interactors removed and their responsibility moved to appropriate services.
21
+ * Refactored printing information about repository loading progress. Now `ReadNode.call(on_error: )` accepts `on_error` callback and you can provide any method proc or lambda there like `lambda {|err| puts err}`.
22
+ * Refactored previous behavior where interactors loaded repository by QueryAssembly interactor. Now it is responsibility of `LoadAssembly` service and other services that require repository just get it through parameter.
23
+ * `clerq new PROJECT` command brings the `lib\clerq_doc.thor` example of publishing and importing existing documents in the current clerq project repository. To see these just copy the file to root project folder near `<project>.thor` file.
24
+
25
+ ## 0.2.1 (2019-11-29)
26
+
27
+ * Enhanced the `Node` class that brings the possibility to provide node id through `{{id: <id>}}` metadata attribute. But it will just skipped when id is already provided by `# [<id>]`.
28
+ * Enhanced `NodeReader` class; now it supports three metadata attributes delimiters - `\n`, `;`, and `,` that can be mixed.
29
+ * `CheckAssembly` interactor replaced by `CheckAssembly` service that provides improved error information with nodes ids and source files names.
30
+ * `file_name` attribute changed to `filename` in `NodeReader`.
31
+
32
+ ## 0.2.0 (2019-11-23)
33
+
34
+ * Started new project [Clerq Video Guide](https://github.com/nvoynov/clerq-video-guide) that provides example of using Clerq.
35
+ * Done massive refactoring of source code; no more gateways.
36
+ * Totally redesigned NodeRepository and TextRepository.
37
+ * Improved interactors caused by gateways throwing out.
38
+ * Improved tests suite; no more DEPRECATED Minitest; Dir.mktmpdir is used for sandbox.
39
+ * Improved README to include all the changes mentioned before.
40
+ * Improved `clerq new PROJECT` command; when the `PROJECT` parameter consists of more than one word, it will create `<project>.thor` file that follows to usual ruby file and class naming conventions; e.g. for `user guide` it will create `user_guide.thor` and `class UserGuide < Thor` inside.
41
+ * Shortened `content.md.tt` content
42
+ * Only two templates in the box are left - `default.md.erb` and `pandoc.md.erb`.
43
+ * Thor `error(msg)` in `cli.rb` changed to `stop!(mgs); raise Thor::Error`.
44
+ * Improved CLI for `build`, `check`, `toc`, `node`; now each one checks if the command is running in clerq project, checked if `clerq.yml` or `src` folder exist.
45
+ * Other small improvements.
46
+
47
+ ## 0.1.0 (2019-11-08)
48
+
49
+ First release
data/Gemfile.lock CHANGED
@@ -1,24 +1,24 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- clerq (0.1.0)
5
- thor (~> 0.20.3)
4
+ clerq (0.3.3)
5
+ thor (~> 1.0.1)
6
6
 
7
7
  GEM
8
8
  remote: https://rubygems.org/
9
9
  specs:
10
- minitest (5.13.0)
11
- rake (10.5.0)
12
- thor (0.20.3)
10
+ minitest (5.14.4)
11
+ rake (13.0.1)
12
+ thor (1.0.1)
13
13
 
14
14
  PLATFORMS
15
15
  x64-mingw32
16
16
 
17
17
  DEPENDENCIES
18
- bundler (~> 1.17)
18
+ bundler (~> 2.2.3)
19
19
  clerq!
20
- minitest (~> 5.0)
21
- rake (~> 10.0)
20
+ minitest (~> 5.14.2)
21
+ rake (~> 13.0)
22
22
 
23
23
  BUNDLED WITH
24
- 1.17.3
24
+ 2.2.15
data/README.md CHANGED
@@ -1,42 +1,168 @@
1
1
  # Clerq
2
2
 
3
- Gem `clerq` represents an unusual but effective way of writing and managing requirements. It resembles some static site builders and was inspired by those. Actually this gem provides the ability to write requirements in separate files and combine those to a unified consistent requirements source for any future purposes.
3
+ __What is Clerq?__
4
4
 
5
- Sounds too simple? Combine it with a modern text editor that supports markdown, place repository under `Git`, install `Pandoc` to convert it to any supported format. Create your own commands through `Thor` to automate every piece of work that can be automated. Give it a try!
5
+ The Clerq is a toolbox for manipulating the hierarchy of text data placed in separate markdown files. It implements three basic ideas:
6
+
7
+ 1. Text data repository in file system, based on markdown files with few extra conventions.
8
+ 2. Ruby gem that provides access to the text hierarchy from the repository.
9
+ 3. Basic CLI to manage the repository and compile the text data to documents based on erb-templates.
10
+
11
+ __What for?__
12
+
13
+ The Clerq is suitable for writing thick structured texts. The initial purpose for the system was the "requirements management in file system" and it supposed to help in writing stuff like Vision, RFP, URD, SRS, SAD, and deriving various requirements based artifacts. But now it seems much wider.
6
14
 
7
15
  ## Installation
8
16
 
9
- Add this line to your application's Gemfile:
17
+ Install it yourself as:
10
18
 
11
- ```ruby
12
- gem 'clerq'
19
+ $ gem install clerq
20
+
21
+ For Ruby 2.X you should use version 0.3.2:
22
+
23
+ $ gem install clerq -v 0.3.2
24
+
25
+ It's because of keyword arguments changes in Ruby 3
26
+
27
+ ## Usage
28
+
29
+ The Clerq is entirely based on one single domain entity `Node` that represents a node of tree hierarchy and provides `id`, `title`, `body`, and `metadata` attributes. It supposes the following simple workflow:
30
+
31
+ * you create files with text content,
32
+ * and manipulate the data by scripts.
33
+
34
+ ### Project
35
+
36
+ The Clerq project lives in the following folders structure that will be created by `clerq new <project>`:
37
+
38
+ * `bin/` - for output documents;
39
+ * `bin/assets` - for assets;
40
+ * `knb/` - knowledge base;
41
+ * `lib/` - place for extra Ruby code;
42
+ * `src/` - source data repository;
43
+ * `tt/` - templates;
44
+ * `<project>.thor` - see [Scripting](#scripting);
45
+ * `clerq.yml` - project settings;
46
+ * `README.md`.
47
+
48
+ ### Writing
49
+
50
+ The Clerq reads nodes from a set of separate files and assembles it to a single hierarchy. There are a few conventions for a separate file that will become a part of hierarchy.
51
+
52
+ #### Files
53
+
54
+ The first convention is the scheme how a markdown content becomes the `Node` entity.
55
+
56
+ ```markdown
57
+ # [p2] Part two
58
+ {{parent: top}}
59
+
60
+ Body
13
61
  ```
14
62
 
15
- And then execute:
63
+ Where
16
64
 
17
- $ bundle
65
+ * `#` familiar markdown header that indicates a new `node`;
66
+ * `[p1]` is an optional identifier that becomes `node.id`;
67
+ * `Part two` is an optional `node.title`;
68
+ * `{{parent: top}}` in an optional metadata section that becomes `node.meta`;
69
+ * and finally `Body` is an optional `node.body`.
18
70
 
19
- Or install it yourself as:
71
+ ```markdown
72
+ # Part two
73
+ {{id: p1, parent: top}}
20
74
 
21
- $ gem install clerq
75
+ Body
76
+ ```
22
77
 
23
- ## Usage
78
+ Every new header (`#`) at any level indicates a new node. When a file contains headers of different levels, the nodes will be created in a natural hierarchy based on header levels. So as the result of reading the content below, the Clerq will create the natural hierarchy with root node `Top` that holds two child nodes `First` and `Second`.
79
+
80
+ ```markdown
81
+ # Top
82
+ ## First
83
+ ## Second
84
+ ```
85
+
86
+ One more extra thing is links. You can place links to other nodes in the body section of the file content by using `[[<id>]]` macro. It can be handled in templates.
87
+
88
+ #### IDs
89
+
90
+ To be able to build a hierarchy or to refer to other nodes, one needs each node to have its unique id. And you can pass it straight into markdown header `# [node id] node title` or provide it through `{{id: }}`.
91
+
92
+ ID can start with one dot, like `[.suffix]`, and clerq will build the node id as `node.parent_id + node.id`.
93
+
94
+ When and ID is not provided, the Clerq will generate it automatically. Let's see the example of node:
95
+
96
+ ```markdown
97
+ # User requirements
98
+ ## Requirement 1
99
+ ## Requirement 2
100
+ # Function requirements
101
+ ## [cm] Components
102
+ ### [.fm] File manager
103
+ ### Logger
104
+ ```
105
+
106
+ According to rules mentioned above the example will be translated as followed:
107
+
108
+ ```markdown
109
+ # [01] User requirements
110
+ ## [01.01] Requirement 1
111
+ ## [01.02] Requirement 2
112
+ # [02] Function requirements
113
+ ## [cm] Components
114
+ ### [cm.fm] File manager
115
+ ### [cm.01] Logger
116
+ ```
24
117
 
25
- To see the list of all standard clerq commands type in console `clerq help` and follow the printed instructions.
118
+ #### Meta
26
119
 
27
- To see the list of all specific for the project commands type `thor help <project>`
120
+ The excerpt, the text in brackets `{{ }}` that follows by the header, contains node attributes. And the second convention mentioned in [Writing](#writing) section is the followed magic metadata attributes that specify parameters of a hierarchy:
28
121
 
29
- Actually the best way to start with Clerq is to see it in action through [Promo](#promo). Just start from copying promo content and running some commands.
122
+ 1. `id: <id>` specifies id through metadata; when in provided together with `# [<id>]`, the last has priority;
123
+ 2. `parent: <id>` indicates that the node belongs to a node with specified `id`;
124
+ 3. `order_index: <id1> <id2>` indicates that child nodes must be lined up in specified order.
30
125
 
31
- ### Creating new project
126
+ You can place in metadata any simple string that suitable for providing additional information like status, originator, author, priority, etc. E.g.
127
+
128
+ ```markdown
129
+ # [r.1]
130
+ {{parent: r, status: draft}}
131
+
132
+ # [r.2]
133
+ {{parent: r
134
+ }}
135
+
136
+ # [r.3]
137
+ {{
138
+ parent: r}}
139
+ ```
140
+
141
+ #### Assets
142
+
143
+ When you want to provide some assets or links to something outside the repository you can provide the lint to the assets. Put the asset in the `bin/assets` folder and specify the link.
144
+
145
+ ```markdown
146
+ # [ent] Entities
147
+
148
+ The following picture shows something
149
+
150
+ ![Image](assets/er.png)
151
+ ```
152
+
153
+ ### CLI
154
+
155
+ Clerq provides CLI that is based on Thor, so all standard thor features are supported. To print all Clerq commands type `$ clerq help` in your console. To see the list of all the project-specific commands type `thor help <project>`.
156
+
157
+ #### Create new project
32
158
 
33
159
  To create a new project run `new` command:
34
160
 
35
161
  $ clerq new <project_name>
36
162
 
37
- ### Create new item
163
+ #### Create new file
38
164
 
39
- The simplest way of adding new items to the project is to add a new file to the `src` directory. Of course, Clerq also provides the command `node`
165
+ The simplest way of adding new items to the project is to add a new file to the `src` directory. Of course, Clerq also provides the command `node` that can create template-based files:
40
166
 
41
167
  $ clerq node ID [TITLE] [-t TEMPLATE]
42
168
 
@@ -46,13 +172,13 @@ If you are using images or other assets, you should place it to `bin/assets` dir
46
172
 
47
173
  __Templates__
48
174
 
49
- You also can prepare your own templates it `tt` folder and provide template through `-t/--template` option. The content of the template file will be placed on the body of the requirement.
175
+ You also can prepare your own templates it `tt` folder and provide template through `-t/--template` option. The content of the template will be placed on the created file.
50
176
 
51
- ### Check repository
177
+ #### Check repository
52
178
 
53
179
  Because of lots of handwriting there can be some specific errors in repository. The most obvious are:
54
180
 
55
- * non-unique requirements identifiers;
181
+ * non-unique identifiers;
56
182
  * links to and id that does not exist:
57
183
  * for `parent` attribute;
58
184
  * in `order_index`;
@@ -62,9 +188,9 @@ The system provides command `clerq check` that will check the repository for the
62
188
 
63
189
  $ clerq check
64
190
 
65
- ### Build project
191
+ #### Build project
66
192
 
67
- Clerq provides the ability to combine all requirements from the project repository and create final document. To create such document you can use `clerq build` command:
193
+ Clerq provides the ability to combine all the text data from the project repository and create the final document. To create such document you can use `clerq build` command:
68
194
 
69
195
  $ clerq build
70
196
 
@@ -81,182 +207,183 @@ You also can specify these settings through `clerq build` options:
81
207
  * `-t/--template TEMPLATE` provides the ability to specify template;
82
208
  * `-o/--output FILE_NAME` provides the ability to specify output file name.
83
209
 
84
- __Query requirements__
210
+ __Queries__
85
211
 
86
- Clerq also provides ability to query requirements that meet query criteria. To query requirements you should use `-q/--query QUERY_STRING` where `QUERY_STRING` is ruby code that will test if each node meets the `QUERY_STRING`. For example, `node.tile == 'Functional requirements'` or `node.id == 'us'`.
212
+ Clerq provides the ability to query data that match query criteria. To query data you should use `-q/--query QUERY_STRING` option where `QUERY_STRING` is ruby code that will test if each node matches the `QUERY_STRING`. For example, `node.tile == 'Functional requirements'` or `node.id == 'us'`.
87
213
 
88
- ### Print TOC
214
+ #### Print TOC
89
215
 
90
216
  Sometimes it helpful to check repository structure by `clerq toc` command. The command also supports `-q/--query QUERY_STRING` option.
91
217
 
92
- ## Known issues
218
+ ### Scripting
93
219
 
94
- ### Failed test
220
+ The section assumes that you are familiar with Ruby or some other programming language.
95
221
 
96
- Some tests of CLI fail by `$ bundle exec rake test` but pass individually one by one through `$ bundle exec rake test TEST=test/cli/cli_build_spec.rb` and I haven't caught the reason.
222
+ Using the basic commands described in [CLI](#cli) section gives you just the ability to create final documents or other output. But this is just the tip of the iceberg, just the beginning, and you can do much more than that with Clerq.
97
223
 
98
- ### Thor version
224
+ A usual scenario will consist of two simple steps:
99
225
 
100
- The one issue I certain in is when you are using different version of thor, your custom scripts won't work.
226
+ 1. Get data hierarchy from the repository.
227
+ 2. Do some processing of the hierarchy.
101
228
 
102
- ## Structure
229
+ #### Node class
103
230
 
104
- ### Project
231
+ The [Writing](#writing) section provides the basic knowledge to understand Clerq, and now it is the right time to see the [Node class](https://github.com/nvoynov/clerq/blob/master/lib/clerq/entities/node.rb). It implements the Composite pattern.
105
232
 
106
- The Clerq project has the following folders structure by default (that will be created by `clerq new <project>`):
233
+ #### Services
107
234
 
108
- * `bin/` - for output documents;
109
- * `bin/assets` - for assets;
110
- * `knb/` - knowledge base;
111
- * `lib/` - place for Ruby code;
112
- * `src/` - place for requirements;
113
- * `tt/` - templates;
114
- * `<project>.thor` - file with automated tasks (see more in [Automating](#automating));
115
- * `clerq.yml` - project settings;
116
- * `README.md`.
117
-
118
- ### Repository
119
-
120
- Place requirements to the `src` folder. You can group your requirements by different folders and subfolders - Clerq load all the files of `src` including all subfolders at any level of nesting.
235
+ Clerq provides the following main service objects:
121
236
 
122
- ### Node
237
+ * `LoadAssembly` loads whole repository to Node class;
238
+ * `CheckAssembly` checks the assembly for errors (ids and links);
239
+ * `QueryNode` provides ability to query nodes from assembly;
240
+ * `QueryTemplate` return template by the template name;
241
+ * `CreateNode` crates new node in the repository;
242
+ * `RenderNode` return text rendered by ERB.
123
243
 
124
- Each requirement is a markdown file with a few additional compliances (will be explained below) where every file can contain any number of requirements. Let's meet some files ...
244
+ The first part of each repository related task is to get repository assembly. It can be performed through `NodeRepository#assemble` or `LoadAssembly.call()`. Each of these methods returns Node that provides [Enumerable](https://ruby-doc.org/core-2.6.5/Enumerable.html) interface.
125
245
 
126
- **content.md**
246
+ Let's see an example. Assume that you are developing a "User requirements document" and the project policy requires that each user requirement must have the parameter called `originator`. You can write the policy as followed:
127
247
 
128
- ```markdown
129
- # 1 Introduction
130
- {skip_meta: true}
131
- ## 1.1 Purpose
132
- ## 1.2 Scope
133
- ## 1.3 References
134
- ## 1.4 Definitions
135
- ## 1.5 Overview
136
- # [f] Requirements
137
- # [i] Interfaces
138
- # [n] Non-functional requirements
139
- # [c] Design constraints
248
+ ```ruby
249
+ require 'clerq'
250
+ include Clerq::Services
251
+
252
+ # supposed you have something like user requirements document
253
+ node = LoadAssembly.()
254
+ node = QueryNode.(node: node, query: "node.title == 'User requirements'")
255
+ miss = node.drop(1).select{|n| n[:originator].empty? }
256
+ unless miss.empty?
257
+ errmsg = "`Originator` is missed for the following nodes:\n"
258
+ errmsg << miss.map(&:id).join(', ')
259
+ raise Error, errmsg
260
+ end
140
261
  ```
141
262
 
142
- **fm.md**
143
-
144
- ```markdown
145
- # [.fm] File manager
146
- {{parent: f}}
147
-
148
- The system shall provide the `File Manager` component. The component shall provide the following features:
263
+ Instead of adding extra scripts files somewhere in the project, you can write tasks in `<project>.thor` (see [Automating](#automating) section for details.)
149
264
 
150
- {{@@list}}
265
+ #### Root Node
151
266
 
152
- ## Read folders structure
153
- ## Read file content
154
- ## Load ".md"
155
- ## Load ".tt"
156
- ```
267
+ A hierarchy starts form root node and Clerq provides the root node with parameter `title` specified in `clerq.yml` file. The subject is a bit tricky actually and there are few extra considerations I try to explain below (and you can always see tests)
157
268
 
158
- #### Headers
269
+ When your repository stills empty, the Clerq will provide you with the root node. From one point it resembles the NullObject.
159
270
 
160
- Every requirement starts with markdown header. All the text between headers belongs to the requirement.
271
+ When you have a few root nodes in your repository, those become direct childs of the root node. But when your repository contains single root node, the Clerq will return the single node as root node.
161
272
 
162
- #### Identifiers
273
+ The following example does not provide root node and it causes adding root node from `clerq.yml`.
163
274
 
164
- Each requirement must have its own unique identifier so that you can refer to it in other parts of the project. That's why the recommended practice is to put id straight into the header `# [requirement_id] requirement title`.
275
+ ```markdown
276
+ # User requirements
277
+ # Functional requirements
278
+ ```
165
279
 
166
- ID can start with one dot, like `[.suffix]`, and clerq will add parent requirement id before. For the followed example, `[.fm]` will be translated to `[cm.fm]`.
280
+ But this one provides, and the root node will be `Product SRS`.
167
281
 
168
- ```
169
- # 3 Function requirements
170
- ## [cm] Components
171
- ### [.fm] File manager
172
- ### Logger
282
+ ```markdown
283
+ # Product SRS
284
+ ## User requirements
285
+ ## Functional requirements
173
286
  ```
174
287
 
175
- When an identifier is not provided, Clerq will generate it automatically, and you can combine requirements that have id and requirements that does not. For the example above, the `Logger` will be identified as `[cm.01] Logger`.
288
+ The QueryAssembly follows the similar logic
176
289
 
177
- #### Attributes
290
+ * When query result is empty, the Clerq will provide result with QueryNullNode (node.title == `Query`, node[:query] == QUERY_STRING)
291
+ * When query result contains single node, it becomes a root query node.
292
+ * When query result contains more than one, those becomes a child of root query node.
178
293
 
179
- The excerpt, the text in brackets `{{ }}` that follows by the header, contains requirement attributes. You can place here anything you need to provide additional information, like status, source, author, priority, etc. All the following examples are correct.
294
+ ### Automating
180
295
 
181
- ```
182
- # [r.1]
183
- {{parent: r; skip_meta: true}}
296
+ The Clerq creates `<project>.thor` where you can place your project-specific tasks. It is a standard [Thor](https://github.com/erikhuda/thor) that brings you all script automation power through CLI and to dive deeper just spend a few minutes reading [the poject wiki](https://github.com/erikhuda/thor/wiki).
184
297
 
185
- # [r.2]
186
- {{parent: r
187
- skip_meta: true}}
298
+ Let's move the code from [Scripting](#scripting) section to the `<project>.thor` file:
188
299
 
189
- # [r.3]
190
- {{
191
- parent: r
192
- skip_meta: true
193
- }}
300
+ ```ruby
301
+ require 'clerq'
302
+ include Clerq::Services
303
+
304
+ class MyDocument < Thor
305
+ namespace :mydoc
306
+
307
+ no_commands {
308
+ def stop_on_error!(errmsg)
309
+ raise Thor::Error, errmsg
310
+ end
311
+ }
312
+
313
+ desc 'check_originator', 'Check :originator'
314
+ def check_originator
315
+ node = LoadAssembly.()
316
+ node = QueryAssembly.(node: node, query: "node.title == 'User requirements'")
317
+ miss = node.drop(1).select{|n| n[:originator].empty? }
318
+ unless miss.empty?
319
+ errmsg = "`Originator` is missed for the following nodes:\n"
320
+ errmsg << miss.map(&:id).join(', ')
321
+ stop_on_error!(errmsg)
322
+ end
323
+ end
324
+ end
194
325
  ```
195
326
 
196
- The next attributes are **system attributes** and these influence to Clerq behavior:
327
+ And then you can run the task by
197
328
 
198
- * `order_index: feature1 feature2` will sort child requirements in provided order;
199
- * `parent: f` will place the requirement as a child of parent requirement `[f]`.
329
+ $ thor mydoc:check_originator
200
330
 
201
- All other attributes (`status`, `source`, etc.) are **user attributes** and do not influence Clerq behavior. These attributes are holding in requirement's attributes and can be used for publishing or automation purpose. One of such `skip_meta: true` used producing output document.
331
+ This example is just very basic and your automation scripts could be much more complex.
202
332
 
203
- #### Assets
333
+ Another quick example is [clerq.thor] (https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket `{{}}` in Jekyll and now I run `thor clerqsrc:docs` every time after changing this file.
204
334
 
205
- If you need to add an image or some other material into a requirements body, put it in the `bin/assets` folder and specify the link
335
+ ### Templating
206
336
 
207
- ```markdown
208
- # [ent] Entities
337
+ The Clerq provides the ability to precise adjusting the output for `clerq build` command by erb-templates and gives you two basic templates from the box.
209
338
 
210
- ... the following picture shows conceptual entity relations diagram
339
+ * [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb) that just combines all nodes to one markdown document;
340
+ * [pandoc.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/pandoc.md.erb) is more advanced, it produces [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and provides three followed macros for node body:
341
+ * `{{@@list}}` - replaces the macro with the list of child nodes;
342
+ * `{{@@tree}}` - replaces the macro with the tree of child nodes;
343
+ * `{{@@skip}}` - skip all content inside the brackets.
211
344
 
212
- ![Image](assets/er.png)
213
- ```
345
+ ### Publishing
214
346
 
215
- ### Templating
347
+ In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.rb) I provided the example of basic documents management tasks (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
216
348
 
217
- To customize Clerq output the system provides `erb` templates. You have a lot of possibilities here if you are familiar with Ruby. Clerq distributions provides two basic templates - `default.md.erb` and `pandoc.md.erb`.
349
+ * `thor clerq:doc:publish` will create `<project>.docx` and `<project>.html`;
350
+ * `thor clerq:doc:grab` will import provided document into the current project repository.
218
351
 
219
- The first one combines all requirements to one document and there no requirements transformation actually.
352
+ ## Known issues
220
353
 
221
- The second one has a lot of features and provides a good example of how to add new features in the requirements body. It handles three macros:
354
+ ### Thor version
222
355
 
223
- * `{{@@list}}` - replaces the macro with the list of child requirements;
224
- * `{{@@tree}}` - replaces the macro with the tree of child requirements;
225
- * `{{@@skip}}` - skip all content inside the brackets.
356
+ The one issue I certain in is when you are using different version of thor, your custom scripts won't work.
226
357
 
227
- `pandoc.md.erb` generates Pandoc markdown and can be used to convert the output of the template in any supported format. You also can use relative requirements links here. An example of using Pandoc to generate `docx` can be found in [Promo](#promo).
358
+ ### Test suite
228
359
 
229
- ### Automating
360
+ Because `default.md.erb` and `pandoc.md.erb` have inside the same class `MarkupNode`, sometimes one of `default_spec.rb` or `pandoc_spec.rb` fails.
230
361
 
231
- You can and should extend the standard Clerq CLI by your own commands. See `<project>.thor` file as an example and call for action. It is all the Ruby code and the main point is to get requirements collection and then transform it to anything you want. It is the `Thor` gem that does all work related to CLI.
362
+ ## Some considerations
232
363
 
233
- You can find some examples of custom automating in [Promo](#promo), and I hope to provide some more examples in the future.
364
+ ### Some obvious things
234
365
 
235
- ## Promo
366
+ Use modern text editor that provides projects tree. like Atom, Sublime, etc.
236
367
 
237
- The clerq provides the promotion project `promo` than contains requirements to the clerq. You can copy the `promo` content to the current clerq repository by `clerq promo` command.
368
+ Hold your projects in Git.
238
369
 
239
- The promo provides few specific commands that created to show you the way how to extend clerq. See `promo.thor` for details.
370
+ Use pandoc for generating output in different formats
240
371
 
241
- ## History
372
+ ### MarkupNode
242
373
 
243
- During 4 years work for my previous employer I participated in dozen software development and software reengineering projects and developed dozen bulk SRS and SAD documents. All those documents were developed in MS Word as a corporate standard format for all project documentation. And every of those often cause some headache usually with casual losses of style formatting or dead halt of Microsoft Word.
374
+ Don't like the current dirty solution with templates and incorporated MarkupNode that does all that stuff with macro. It is the first attempt to provide template that can skip comments.
244
375
 
245
- When I left the employer, I decided to create a small toolkit for writing software documentation. The idea was to hold requirements in Yaml, each item in a separate file, and to provide reach features for effort estimation and prioritizing based on requirements. The first attempt was failed but brought some output. Throw out extra features! One item per file is a hell to author (but for a developer it was rather practical).
376
+ ### Several artifacts
246
377
 
247
- As the result of the first fail, the gem `Creq` was born. Exra features were thrown out. An author not limited to Yaml and uses Markdown now; he can write as many topics as he wants in one file. And for my new employer all requirements were developed in Creq. Some lessons were learn, some peculiarities were met, and then I decided to do some reengineering and developed Clerq. So here we are and now I have no claims to the subject of requirements writing and management.
378
+ Because Clerq has `-q/--query QUERY_STRING` option you can be interested in developing several different artifacts in one project.
248
379
 
249
- * One Clerq project per one document!
250
- * Document versioning and authors collaboration are under Git!
251
- * Any text editor is suitable for requirements writing! Of course, markdown syntax highlighting feature is desired.
252
- * Single consistent requirements source and many templates for final documents (I like to left "TBD", "TODO" and other comment for myself, reviewer, and developers but it cannot be left in documents releases.)
253
- * All extra repeated job for certain project can be automated through Thor.
380
+ I was considering such an example to develop all software project documents in one clerq project but decided that it is more properly to develop one single artifact per project because usually, each artifact has its own develop-review-release cycle.
254
381
 
255
- The last thing should be mentioned is drifting the original purpose of requirements management to compilation bulk documents from small pieces, and a requirement here is just a piece of text that can express just anything.
382
+ Also, I was considering to add some kind of a "top" project that is just a wrapper for individual projects inside (each of them is the clerq project, and the top project just provides a specific set of commands.) I was speculating about some kind of shared content and tracing nodes between different artifacts. But for the moment I have no full-fledged vision.
256
383
 
257
384
  ## Development
258
385
 
259
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
386
+ The project is bundled, so after checking out the repo, run `bundle` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
260
387
 
261
388
  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).
262
389