actionable-docs 1.0.0.pre1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 1034dc9692667f5b45a2312d121a57c81a875f2f9e32e8d5fff26264b3be4a32
4
+ data.tar.gz: a30dfd18d1a27db99a31efee79c9cad44a60fbb4b39f1230989680d0bd5680e0
5
+ SHA512:
6
+ metadata.gz: 41c3d6fcb31e50ed9a5fbc601d83eeb1cee6ea7ce7bfdadc8330c64d514b18edcfb208bc6d00e56e9c55a19ef3933ce1d1865d006bad6bc111da560554d9e5de
7
+ data.tar.gz: 5d0944fee20260133da4e9c9a14eb99cea32abd61940164d61224986384395f0cccb3732212d6dccc7c96adf74f9c49bf09a69f90818a9b6ccaab60d5209a2fc
data/CHANGELOG.md ADDED
@@ -0,0 +1,6 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ - First release: `Actionable::Docs.markdown`, `title`, `path_for`, `write` and `stale`, and the `actionable:docs`
6
+ and `actionable:docs:check` rake tasks from `Actionable::Docs::Tasks.define`.
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Adrian Madrid
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,86 @@
1
+ # actionable-docs
2
+
3
+ Turn an [actionable-rb](../../gems/actionable) action into a page someone outside the code can read: what it does,
4
+ in what order, why it can stop, and what happens after. The page is Markdown with one Mermaid flowchart, built from
5
+ the action's declarations and descriptions. A rake task writes the pages, and a check task fails when they drift.
6
+
7
+ ```ruby
8
+ gem 'actionable-docs'
9
+ ```
10
+
11
+ Version `1.0.0.pre1`. Ruby 3.3 or newer. Load it with `require 'actionable/docs'`.
12
+
13
+ ## A page from an action
14
+
15
+ Give the action and its parts a `desc`, and the page uses those words. Anything without one gets words made from its
16
+ name.
17
+
18
+ ```ruby run
19
+ require 'actionable/docs'
20
+
21
+ module Framing
22
+ class MountPrint < Actionable::Action
23
+ desc 'Mounts a customer print behind glass.'
24
+
25
+ input { required :width_cm, :integer, desc: 'Width of the print' }
26
+
27
+ fails :glass_chipped, 'the glass pane is chipped', retry: false
28
+
29
+ step :cut_mat, desc: 'Cut the mat to size'
30
+ step :fit_glass, if: :glass_ordered?
31
+
32
+ private
33
+
34
+ def glass_ordered? = true
35
+ def cut_mat = nil
36
+ def fit_glass = nil
37
+ end
38
+ end
39
+
40
+ page = Actionable::Docs.markdown(Framing::MountPrint)
41
+
42
+ Actionable::Docs.title(Framing::MountPrint) # => "Mount print"
43
+ Actionable::Docs.path_for(Framing::MountPrint) # => "framing/mount_print.md"
44
+ page.lines.first # => "# Mount print\n"
45
+ page.include?('2. Fit glass (only when glass ordered)') # => true
46
+ page.include?('- **Glass chipped**: the glass pane is chipped _(don\'t retry)_ `glass_chipped`') # => true
47
+ ```
48
+
49
+ The page has, in order: the title and description, the flowchart, the numbered steps, "It can stop because" and
50
+ "It can finish early because" (the declared failures and skips), "What happens after" (the hooks), "What it needs"
51
+ and "What it produces" (the input and output fields), and "Also runs" for actions found in the source, then a
52
+ line saying the page is generated. Empty sections are left out.
53
+
54
+ In the chart, a child action is one box that links to its own page; it never opens up inline. A guard is a
55
+ decision, and a case step is a decision with one edge per branch. Failures and skips hang off Start, since
56
+ `describe` doesn't say which step ends with which code.
57
+
58
+ ## Writing and checking pages
59
+
60
+ Every call needs a named class: an anonymous `Class.new(Actionable::Action)` raises `ArgumentError`.
61
+ `Docs.write(actions, dir:)` writes each page and returns the paths. `Docs.stale(actions, dir:)` returns the pages
62
+ that are missing or out of date, and writes nothing.
63
+
64
+ For a Rakefile:
65
+
66
+ ```ruby
67
+ require 'actionable/docs/tasks'
68
+
69
+ Actionable::Docs::Tasks.define(actions: -> { [Framing::MountPrint] }, dir: 'docs/actions')
70
+ ```
71
+
72
+ That gives you `rake actionable:docs` (write the pages) and `rake actionable:docs:check` (fail, listing the stale
73
+ pages, when they differ from fresh ones; run it in CI). Pass `actions:` as a lambda so your app's code loads first.
74
+ Only the actions you list get pages.
75
+
76
+ ## What is and is not covered
77
+
78
+ - Headings are fixed English.
79
+ - No JSON output, no Rails view, and no per-step codes yet.
80
+ - A large action gives a large chart; nothing collapses it.
81
+
82
+ Signatures are in `sig/`.
83
+
84
+ ## Docs
85
+
86
+ The guide on the docs site, with every example run in CI: https://gliders-rb.github.io/adapters/process-docs/
@@ -0,0 +1,95 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Docs
5
+ # The Mermaid flowchart of one action: the happy path top to bottom, decisions for guards and case steps, each
6
+ # child action one linked box, and one exit node per declared failure or skip (AD-B20..AD-B24).
7
+ # @api private
8
+ class Flowchart
9
+ # @param action [Class] a named action
10
+ def initialize(action)
11
+ @action = action
12
+ @info = action.describe
13
+ @lines = ['flowchart TD', ' start([Start])']
14
+ @count = 0
15
+ end
16
+
17
+ # @return [String] the chart text, ending with a newline
18
+ def to_s
19
+ tails = Array(@info[:steps]).reduce([['start', nil]]) { |open, entry| step(entry, open) }
20
+ @lines << ' done([Done])'
21
+ connect(tails, 'done')
22
+ exits
23
+ "#{@lines.join("\n")}\n"
24
+ end
25
+
26
+ private
27
+
28
+ # Adds +entry+ after the +open+ ends; returns the ends the next step hangs off, as +[node, edge label]+ pairs.
29
+ def step(entry, open)
30
+ guard = entry[:guard] || {}
31
+ skipped = []
32
+ { if: %w[yes no], unless: %w[no yes] }.each do |key, (run, skip)|
33
+ next unless guard.key?(key)
34
+
35
+ decision = add('g', "{\"#{escape(Words.guard_words(guard[key]))}?\"}")
36
+ connect(open, decision)
37
+ open = [[decision, run]]
38
+ skipped << [decision, skip]
39
+ end
40
+ body(entry, open) + skipped
41
+ end
42
+
43
+ def body(entry, open)
44
+ return case_body(entry, open) if entry[:type] == :case
45
+
46
+ node = box(entry)
47
+ connect(open, node)
48
+ [[node, nil]]
49
+ end
50
+
51
+ def box(entry)
52
+ child = entry[:name]
53
+ return add('s', "[\"#{escape(Words.plain_label(entry))}\"]") unless child.is_a?(Class)
54
+
55
+ node = add('s', "[[\"#{escape(entry[:description] || Words.title(child))}\"]]")
56
+ @lines << " click #{node} \"#{Words.link(@action, child)}\""
57
+ node
58
+ end
59
+
60
+ def case_body(entry, open)
61
+ decision = add('c', "{\"#{escape(Words.plain_label(entry))}?\"}")
62
+ connect(open, decision)
63
+ ends = Array(entry[:branches]).flat_map { |branch| step(branch[:step], [[decision, Words.on_words(branch[:on])]]) }
64
+ fallback = entry[:default]
65
+ ends + (fallback ? step(fallback, [[decision, 'anything else']]) : [[decision, 'anything else']])
66
+ end
67
+
68
+ def exits
69
+ { failures: %w[f Stops], skips: ['k', 'Finishes early'] }.each do |key, (prefix, verb)|
70
+ @info[key].each_key do |code|
71
+ node = add(prefix, "[/\"#{verb}: #{escape(Words.humanize(code))}\"/]")
72
+ @lines << " start -->|any step| #{node}"
73
+ end
74
+ end
75
+ end
76
+
77
+ def add(prefix, shape)
78
+ @count += 1
79
+ node = "#{prefix}#{@count}"
80
+ @lines << " #{node}#{shape}"
81
+ node
82
+ end
83
+
84
+ def connect(open, target)
85
+ open.each do |from, label|
86
+ @lines << (label ? " #{from} -->|#{escape(label).tr('|', '/')}| #{target}" : " #{from} --> #{target}")
87
+ end
88
+ end
89
+
90
+ def escape(text)
91
+ text.to_s.tr('"', "'")
92
+ end
93
+ end
94
+ end
95
+ end
@@ -0,0 +1,109 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Docs
5
+ # The Markdown page of one action, in the AD-B10 order.
6
+ # @api private
7
+ class Page
8
+ # The page's last line.
9
+ #
10
+ # @return [String]
11
+ FOOTER = "_Generated from the action's declarations by actionable-docs. Edit the action, not this page._"
12
+ # The hook lists in page order, with their lead-in words.
13
+ #
14
+ # @return [Hash{Symbol=>String}]
15
+ HOOKS = { on_success: 'When it succeeds', on_failure: 'When it stops', on_skip: 'When it finishes early',
16
+ after_commit: 'After the database commits', always: 'Every time, at the end' }.freeze
17
+
18
+ # @param action [Class] a named action
19
+ def initialize(action)
20
+ @action = action
21
+ @info = action.describe
22
+ end
23
+
24
+ # @return [String] the page, ending with one newline
25
+ def to_s
26
+ parts = ["# #{Words.title(@action)}"]
27
+ parts << @info[:description] if @info[:description]
28
+ parts << "```mermaid\n#{Flowchart.new(@action)}```"
29
+ parts << steps
30
+ parts.push(*[codes('It can stop because', @info[:failures]), codes('It can finish early because', @info[:skips]),
31
+ hooks, fields('What it needs', @info[:input]), fields('What it produces', @info[:output]),
32
+ calls].compact)
33
+ parts << FOOTER
34
+ "#{parts.join("\n\n")}\n"
35
+ end
36
+
37
+ private
38
+
39
+ def steps
40
+ entries = Array(@info[:steps])
41
+ return "## Steps\n\nIt has no steps." if entries.empty?
42
+
43
+ lines = entries.each_with_index.map { |entry, index| step_line(entry, index + 1) }
44
+ "## Steps\n\n#{lines.join("\n")}"
45
+ end
46
+
47
+ def step_line(entry, number)
48
+ return "#{number}. #{label(entry)}#{Words.guard_suffix(entry[:guard])}" unless entry[:type] == :case
49
+
50
+ head = "#{number}. Depending on #{Words.lower_first(Words.plain_label(entry))}#{Words.guard_suffix(entry[:guard])}:"
51
+ branches = Array(entry[:branches]).map { |branch| branch_line(Words.on_words(branch[:on]), branch[:step]) }
52
+ branches << branch_line('anything else', entry[:default]) if entry[:default]
53
+ [head, *branches].join("\n")
54
+ end
55
+
56
+ def branch_line(words, entry)
57
+ " - #{words}: #{label(entry)}#{Words.guard_suffix(entry[:guard])}"
58
+ end
59
+
60
+ # A step's words, with a child action as a link to its page.
61
+ def label(entry)
62
+ child = entry[:name]
63
+ return Words.plain_label(entry) unless child.is_a?(Class)
64
+
65
+ "[#{entry[:description] || Words.title(child)}](#{Words.link(@action, child)})"
66
+ end
67
+
68
+ def codes(heading, declarations)
69
+ return nil if declarations.empty?
70
+
71
+ lines = declarations.map do |code, declaration|
72
+ words = declaration[:description] || declaration[:message] || Words.humanize(code)
73
+ retry_note = { true => ' _(worth retrying)_', false => " _(don't retry)_" }[declaration[:metadata][:retry]]
74
+ "- **#{Words.humanize(code)}**: #{words}#{retry_note} `#{code}`"
75
+ end
76
+ "## #{heading}\n\n#{lines.join("\n")}"
77
+ end
78
+
79
+ def hooks
80
+ lines = HOOKS.filter_map do |kind, lead|
81
+ entries = @info[:hooks].fetch(kind, [])
82
+ next if entries.empty?
83
+
84
+ "- #{lead}: #{entries.map { |entry| "#{label(entry)}#{Words.guard_suffix(entry[:guard])}" }.join(', ')}"
85
+ end
86
+ lines.empty? ? nil : "## What happens after\n\n#{lines.join("\n")}"
87
+ end
88
+
89
+ def fields(heading, schema)
90
+ return nil if schema.nil? || schema.empty?
91
+ return "## #{heading}\n\nIt takes one of several input shapes." if schema.key?(:discriminated_on)
92
+
93
+ rows = schema.map do |name, field|
94
+ meaning = field[:description] ? field[:description].to_s.gsub('|', '\|') : '—'
95
+ "| #{Words.humanize(name)} | #{meaning} | #{field[:required] ? 'yes' : 'no'} |"
96
+ end
97
+ "## #{heading}\n\n| Field | Meaning | Required |\n|---|---|---|\n#{rows.join("\n")}"
98
+ end
99
+
100
+ def calls
101
+ children = Array(@info[:calls])
102
+ return nil if children.empty?
103
+
104
+ lines = children.map { |child| "- [#{Words.title(child)}](#{Words.link(@action, child)}) (found in source)" }
105
+ "## Also runs\n\n#{lines.join("\n")}"
106
+ end
107
+ end
108
+ end
109
+ end
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'rake'
4
+ require_relative '../docs'
5
+
6
+ module Actionable
7
+ module Docs
8
+ # Rake tasks for a host app: +actionable:docs+ writes the pages, +actionable:docs:check+ fails when the
9
+ # committed pages differ from fresh ones (AD-B32).
10
+ module Tasks
11
+ module_function
12
+
13
+ # Defines the two tasks.
14
+ #
15
+ # @param actions [Array<Class>, Proc] the actions to document, or a callable returning them (called when a task
16
+ # runs, so an app can load its code first)
17
+ # @param dir [String] the docs folder the pages live in
18
+ # @return [void]
19
+ def define(actions:, dir:)
20
+ list = -> { actions.respond_to?(:call) ? actions.call : actions }
21
+ Rake.application.last_description = "Write the action pages into #{dir}"
22
+ Rake::Task.define_task('actionable:docs') do
23
+ Docs.write(list.call, dir: dir).each { |path| puts "actionable-docs: wrote #{path}" }
24
+ end
25
+ Rake.application.last_description = "Fail when a page in #{dir} is missing or out of date"
26
+ Rake::Task.define_task('actionable:docs:check') { Tasks.check(list.call, dir) }
27
+ end
28
+
29
+ # @api private
30
+ # @param actions [Array<Class>]
31
+ # @param dir [String]
32
+ # @return [void]
33
+ def check(actions, dir)
34
+ stale = Docs.stale(actions, dir: dir)
35
+ unless stale.empty?
36
+ abort "actionable-docs: these pages are out of date; run rake actionable:docs and commit them:\n" \
37
+ "#{stale.join("\n")}"
38
+ end
39
+ puts "actionable-docs: #{actions.uniq.size} pages are current"
40
+ end
41
+ end
42
+ end
43
+ end
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Actionable
4
+ module Docs
5
+ # The gem version.
6
+ #
7
+ # @return [String]
8
+ VERSION = '1.0.0.pre1'
9
+ end
10
+ end
@@ -0,0 +1,97 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'pathname'
4
+
5
+ module Actionable
6
+ module Docs
7
+ # The words a page and its chart use: titles, paths, labels, guard and branch words (AD-B2..AD-B4).
8
+ # @api private
9
+ module Words
10
+ # A guard label that is a method name, as opposed to a description.
11
+ #
12
+ # @return [Regexp]
13
+ METHOD_NAME = /\A[a-z_][A-Za-z0-9_]*[?!]?\z/
14
+
15
+ module_function
16
+
17
+ # @param klass [Class] a named action
18
+ # @return [String] its last name segment as words, only the first letter upper case
19
+ def title(klass)
20
+ sentence(split_words(klass.name.to_s.split('::').last.to_s, ' ').downcase)
21
+ end
22
+
23
+ # @param klass [Class] a named action
24
+ # @return [String] the page's relative path, e.g. +workshop/service_bike.md+
25
+ def path_for(klass)
26
+ "#{klass.name.to_s.split('::').map { |segment| split_words(segment, '_').downcase }.join('/')}.md"
27
+ end
28
+
29
+ # @param from [Class] the action whose page holds the link
30
+ # @param to [Class] the linked action
31
+ # @return [String] the relative path from +from+'s page to +to+'s
32
+ def link(from, to)
33
+ Pathname(path_for(to)).relative_path_from(Pathname(path_for(from)).dirname).to_s
34
+ end
35
+
36
+ # @param name [Symbol, String] a method or code name
37
+ # @return [String] +fit_brakes+ as "Fit brakes" (a trailing +?+ or +!+ dropped)
38
+ def humanize(name)
39
+ sentence(name.to_s.sub(/[?!]\z/, '').tr('_', ' '))
40
+ end
41
+
42
+ # @param entry [Hash{Symbol=>Object}] a step entry from +describe+
43
+ # @return [String] its description, or its humanized name (the title for an action step)
44
+ def plain_label(entry)
45
+ return entry[:description] if entry[:description]
46
+
47
+ entry[:name].is_a?(Class) ? title(entry[:name]) : humanize(entry[:name])
48
+ end
49
+
50
+ # @param label [String] a +guard:+ label from +describe+
51
+ # @return [String] a method name as lower-case words; a description as it is
52
+ def guard_words(label)
53
+ METHOD_NAME.match?(label) ? label.sub(/[?!]\z/, '').tr('_', ' ') : label
54
+ end
55
+
56
+ # @param guard [Hash{Symbol=>String}, nil] an entry's +guard:+
57
+ # @return [String] +" (only when ...)"+, +" (skipped when ...)"+, both joined by +and+, or +""+
58
+ def guard_suffix(guard)
59
+ return '' unless guard
60
+
61
+ parts = []
62
+ parts << "only when #{guard_words(guard[:if])}" if guard.key?(:if)
63
+ parts << "skipped when #{guard_words(guard[:unless])}" if guard.key?(:unless)
64
+ " (#{parts.join(' and ')})"
65
+ end
66
+
67
+ # @param value [Object] a branch's +on+ value
68
+ # @return [String] an Array joined with +or+, a Regexp as +matching /src/+, anything else as text
69
+ def on_words(value)
70
+ case value
71
+ when Array then value.join(' or ')
72
+ when Regexp then "matching /#{value.source}/"
73
+ else value.to_s
74
+ end
75
+ end
76
+
77
+ # @param text [String]
78
+ # @return [String] with only its first letter changed to upper case
79
+ def sentence(text)
80
+ text.empty? ? text : text[0].to_s.upcase + text[1..].to_s
81
+ end
82
+
83
+ # @param text [String]
84
+ # @return [String] with only its first letter changed to lower case
85
+ def lower_first(text)
86
+ text.empty? ? text : text[0].to_s.downcase + text[1..].to_s
87
+ end
88
+
89
+ # @param segment [String] a constant name segment
90
+ # @param separator [String]
91
+ # @return [String] +ServiceBike+ split before each capital that follows a lower-case letter or digit
92
+ def split_words(segment, separator)
93
+ segment.gsub(/(?<=[a-z0-9])(?=[A-Z])/, separator)
94
+ end
95
+ end
96
+ end
97
+ end
@@ -0,0 +1,76 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'fileutils'
4
+ require 'actionable'
5
+ require_relative 'docs/version'
6
+ require_relative 'docs/words'
7
+ require_relative 'docs/flowchart'
8
+ require_relative 'docs/page'
9
+
10
+ # The actionable-rb namespace; this gem adds {Docs}.
11
+ module Actionable
12
+ # Process pages for actions: Markdown with a Mermaid flowchart, built from +describe+ and the descriptions, for
13
+ # people who read about an action rather than its code. Nothing here runs an action.
14
+ module Docs
15
+ module_function
16
+
17
+ # The page for one action.
18
+ #
19
+ # @param action [Class] a named Actionable::Action subclass
20
+ # @return [String] Markdown, ending with one newline
21
+ # @raise [ArgumentError] for anything else
22
+ def markdown(action)
23
+ Page.new(checked(action)).to_s
24
+ end
25
+
26
+ # @param action [Class] a named Actionable::Action subclass
27
+ # @return [String] the words of its title, e.g. "Service bike"
28
+ # @raise [ArgumentError] for anything else
29
+ def title(action)
30
+ Words.title(checked(action))
31
+ end
32
+
33
+ # @param action [Class] a named Actionable::Action subclass
34
+ # @return [String] the page's path relative to the docs folder, e.g. +workshop/service_bike.md+
35
+ # @raise [ArgumentError] for anything else
36
+ def path_for(action)
37
+ Words.path_for(checked(action))
38
+ end
39
+
40
+ # Writes every action's page under +dir+, creating folders.
41
+ #
42
+ # @param actions [Array<Class>] named action classes; a repeat is written once
43
+ # @param dir [String] the docs folder
44
+ # @return [Array<String>] the paths written, in the given order
45
+ def write(actions, dir:)
46
+ actions.uniq.map do |action|
47
+ path = File.join(dir, path_for(action))
48
+ FileUtils.mkdir_p(File.dirname(path))
49
+ File.write(path, markdown(action))
50
+ path
51
+ end
52
+ end
53
+
54
+ # The pages under +dir+ that are missing or differ from a fresh one. Writes nothing.
55
+ #
56
+ # @param actions [Array<Class>] named action classes
57
+ # @param dir [String] the docs folder
58
+ # @return [Array<String>] the stale paths, empty when every page is current
59
+ def stale(actions, dir:)
60
+ actions.uniq.filter_map do |action|
61
+ path = File.join(dir, path_for(action))
62
+ path unless File.file?(path) && File.read(path) == markdown(action)
63
+ end
64
+ end
65
+
66
+ # @api private
67
+ # @param action [Object]
68
+ # @return [Class] the action, when it is a named Actionable::Action subclass
69
+ # @raise [ArgumentError] for anything else
70
+ def checked(action)
71
+ return action if action.is_a?(Class) && action < Actionable::Action && action.name
72
+
73
+ raise ArgumentError, "Actionable::Docs needs a named Actionable::Action subclass, got #{action.inspect}"
74
+ end
75
+ end
76
+ end
@@ -0,0 +1,153 @@
1
+ # The actionable-rb namespace; this gem adds {Docs}.
2
+ module Actionable
3
+ # Process pages for actions: Markdown with a Mermaid flowchart, built from +describe+ and the descriptions, for
4
+ # people who read about an action rather than its code. Nothing here runs an action.
5
+ module Docs
6
+ VERSION: String
7
+
8
+ # The page for one action.
9
+ #
10
+ # _@param_ `action` — a named Actionable::Action subclass
11
+ #
12
+ # _@return_ — Markdown, ending with one newline
13
+ def self.markdown: (Class action) -> String
14
+
15
+ # _@param_ `action` — a named Actionable::Action subclass
16
+ #
17
+ # _@return_ — the words of its title, e.g. "Service bike"
18
+ def self.title: (Class action) -> String
19
+
20
+ # _@param_ `action` — a named Actionable::Action subclass
21
+ #
22
+ # _@return_ — the page's path relative to the docs folder, e.g. +workshop/service_bike.md+
23
+ def self.path_for: (Class action) -> String
24
+
25
+ # Writes every action's page under +dir+, creating folders.
26
+ #
27
+ # _@param_ `actions` — named action classes; a repeat is written once
28
+ #
29
+ # _@param_ `dir` — the docs folder
30
+ #
31
+ # _@return_ — the paths written, in the given order
32
+ def self.write: (::Array[Class] actions, dir: String) -> ::Array[String]
33
+
34
+ # The pages under +dir+ that are missing or differ from a fresh one. Writes nothing.
35
+ #
36
+ # _@param_ `actions` — named action classes
37
+ #
38
+ # _@param_ `dir` — the docs folder
39
+ #
40
+ # _@return_ — the stale paths, empty when every page is current
41
+ def self.stale: (::Array[Class] actions, dir: String) -> ::Array[String]
42
+
43
+ # _@param_ `action`
44
+ #
45
+ # _@return_ — the action, when it is a named Actionable::Action subclass
46
+ def self.checked: (Object action) -> Class
47
+
48
+ # The Markdown page of one action, in the AD-B10 order.
49
+ # @api private
50
+ class Page
51
+ FOOTER: String
52
+ HOOKS: ::Hash[Symbol, String]
53
+
54
+ # _@param_ `action` — a named action
55
+ def initialize: (Class action) -> void
56
+
57
+ # _@return_ — the page, ending with one newline
58
+ def to_s: () -> String
59
+ end
60
+
61
+ # Rake tasks for a host app: +actionable:docs+ writes the pages, +actionable:docs:check+ fails when the
62
+ # committed pages differ from fresh ones (AD-B32).
63
+ module Tasks
64
+ # Defines the two tasks.
65
+ #
66
+ # _@param_ `actions` — the actions to document, or a callable returning them (called when a task runs, so an app can load its code first)
67
+ #
68
+ # _@param_ `dir` — the docs folder the pages live in
69
+ def self.define: (actions: (::Array[Class] | Proc), dir: String) -> void
70
+
71
+ # _@param_ `actions`
72
+ #
73
+ # _@param_ `dir`
74
+ def self.check: (::Array[Class] actions, String dir) -> void
75
+ end
76
+
77
+ # The words a page and its chart use: titles, paths, labels, guard and branch words (AD-B2..AD-B4).
78
+ # @api private
79
+ module Words
80
+ METHOD_NAME: Regexp
81
+
82
+ # _@param_ `klass` — a named action
83
+ #
84
+ # _@return_ — its last name segment as words, only the first letter upper case
85
+ def self.title: (Class klass) -> String
86
+
87
+ # _@param_ `klass` — a named action
88
+ #
89
+ # _@return_ — the page's relative path, e.g. +workshop/service_bike.md+
90
+ def self.path_for: (Class klass) -> String
91
+
92
+ # _@param_ `from` — the action whose page holds the link
93
+ #
94
+ # _@param_ `to` — the linked action
95
+ #
96
+ # _@return_ — the relative path from +from+'s page to +to+'s
97
+ def self.link: (Class from, Class to) -> String
98
+
99
+ # _@param_ `name` — a method or code name
100
+ #
101
+ # _@return_ — +fit_brakes+ as "Fit brakes" (a trailing +?+ or +!+ dropped)
102
+ def self.humanize: ((Symbol | String) name) -> String
103
+
104
+ # _@param_ `entry` — a step entry from +describe+
105
+ #
106
+ # _@return_ — its description, or its humanized name (the title for an action step)
107
+ def self.plain_label: (::Hash[Symbol, Object] entry) -> String
108
+
109
+ # _@param_ `label` — a +guard:+ label from +describe+
110
+ #
111
+ # _@return_ — a method name as lower-case words; a description as it is
112
+ def self.guard_words: (String label) -> String
113
+
114
+ # _@param_ `guard` — an entry's +guard:+
115
+ #
116
+ # _@return_ — +" (only when ...)"+, +" (skipped when ...)"+, both joined by +and+, or +""+
117
+ def self.guard_suffix: (::Hash[Symbol, String]? guard) -> String
118
+
119
+ # _@param_ `value` — a branch's +on+ value
120
+ #
121
+ # _@return_ — an Array joined with +or+, a Regexp as +matching /src/+, anything else as text
122
+ def self.on_words: (Object value) -> String
123
+
124
+ # _@param_ `text`
125
+ #
126
+ # _@return_ — with only its first letter changed to upper case
127
+ def self.sentence: (String text) -> String
128
+
129
+ # _@param_ `text`
130
+ #
131
+ # _@return_ — with only its first letter changed to lower case
132
+ def self.lower_first: (String text) -> String
133
+
134
+ # _@param_ `segment` — a constant name segment
135
+ #
136
+ # _@param_ `separator`
137
+ #
138
+ # _@return_ — +ServiceBike+ split before each capital that follows a lower-case letter or digit
139
+ def self.split_words: (String segment, String separator) -> String
140
+ end
141
+
142
+ # The Mermaid flowchart of one action: the happy path top to bottom, decisions for guards and case steps, each
143
+ # child action one linked box, and one exit node per declared failure or skip (AD-B20..AD-B24).
144
+ # @api private
145
+ class Flowchart
146
+ # _@param_ `action` — a named action
147
+ def initialize: (Class action) -> void
148
+
149
+ # _@return_ — the chart text, ending with a newline
150
+ def to_s: () -> String
151
+ end
152
+ end
153
+ end
metadata ADDED
@@ -0,0 +1,76 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: actionable-docs
3
+ version: !ruby/object:Gem::Version
4
+ version: 1.0.0.pre1
5
+ platform: ruby
6
+ authors:
7
+ - Adrian Madrid
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: actionable-rb
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - ">="
17
+ - !ruby/object:Gem::Version
18
+ version: 2.0.0.pre1
19
+ - - "<"
20
+ - !ruby/object:Gem::Version
21
+ version: '3'
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - ">="
27
+ - !ruby/object:Gem::Version
28
+ version: 2.0.0.pre1
29
+ - - "<"
30
+ - !ruby/object:Gem::Version
31
+ version: '3'
32
+ description: Renders each action as a page (steps, why it can stop, what happens after,
33
+ what it needs and produces) from its declarations, with rake tasks that write the
34
+ pages and fail when they drift.
35
+ email:
36
+ - adrian.madrid@timeworxs.com
37
+ executables: []
38
+ extensions: []
39
+ extra_rdoc_files: []
40
+ files:
41
+ - CHANGELOG.md
42
+ - LICENSE.txt
43
+ - README.md
44
+ - lib/actionable/docs.rb
45
+ - lib/actionable/docs/flowchart.rb
46
+ - lib/actionable/docs/page.rb
47
+ - lib/actionable/docs/tasks.rb
48
+ - lib/actionable/docs/version.rb
49
+ - lib/actionable/docs/words.rb
50
+ - sig/actionable-docs.rbs
51
+ homepage: https://github.com/gliders-rb/gems
52
+ licenses:
53
+ - MIT
54
+ metadata:
55
+ source_code_uri: https://github.com/gliders-rb/gems/tree/main/adapters/actionable-docs
56
+ changelog_uri: https://github.com/gliders-rb/gems/blob/main/adapters/actionable-docs/CHANGELOG.md
57
+ rubygems_mfa_required: 'true'
58
+ rdoc_options: []
59
+ require_paths:
60
+ - lib
61
+ required_ruby_version: !ruby/object:Gem::Requirement
62
+ requirements:
63
+ - - ">="
64
+ - !ruby/object:Gem::Version
65
+ version: '3.3'
66
+ required_rubygems_version: !ruby/object:Gem::Requirement
67
+ requirements:
68
+ - - ">="
69
+ - !ruby/object:Gem::Version
70
+ version: '0'
71
+ requirements: []
72
+ rubygems_version: 3.6.9
73
+ specification_version: 4
74
+ summary: 'Process pages for actionable-rb actions: Markdown and a Mermaid flowchart
75
+ a product manager can read.'
76
+ test_files: []