asgard 0.5.1 → 0.6.1

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.
Files changed (106) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +272 -99
  3. data/README.md +147 -46
  4. data/bin/asgard +10 -0
  5. data/lib/asgard/base/dependency_graph.rb +19 -11
  6. data/lib/asgard/base/dispatch.rb +272 -32
  7. data/lib/asgard/base/registry.rb +7 -3
  8. data/lib/asgard/base/task_dsl.rb +6 -0
  9. data/lib/asgard/base.rb +147 -9
  10. data/lib/asgard/declarations.rb +21 -0
  11. data/lib/asgard/doctor/report.rb +5 -1
  12. data/lib/asgard/doctor/task_sections.rb +11 -3
  13. data/lib/asgard/doctor.rb +41 -31
  14. data/lib/asgard/jobs/commands.rb +183 -0
  15. data/lib/asgard/jobs/declaration.rb +149 -0
  16. data/lib/asgard/jobs/launcher.rb +109 -0
  17. data/lib/asgard/jobs/state.rb +195 -0
  18. data/lib/asgard/jobs/stopper.rb +141 -0
  19. data/lib/asgard/jobs.rb +25 -0
  20. data/lib/asgard/kernel_methods.rb +25 -30
  21. data/lib/asgard/leading_flag.rb +26 -0
  22. data/lib/asgard/log.rb +90 -0
  23. data/lib/asgard/pid.rb +113 -0
  24. data/lib/asgard/schedule/commands.rb +68 -18
  25. data/lib/asgard/schedule/declaration.rb +158 -26
  26. data/lib/asgard/schedule/job_files.rb +24 -0
  27. data/lib/asgard/schedule/launchd.rb +57 -21
  28. data/lib/asgard/schedule/systemd.rb +72 -28
  29. data/lib/asgard/schedule/table.rb +48 -26
  30. data/lib/asgard/schedule.rb +49 -9
  31. data/lib/asgard/shell.rb +366 -44
  32. data/lib/asgard/state_dir.rb +90 -0
  33. data/lib/asgard/tasks.rb +8 -0
  34. data/lib/asgard/version.rb +1 -1
  35. data/lib/asgard/watch/changes.rb +26 -1
  36. data/lib/asgard/watch/commands.rb +63 -13
  37. data/lib/asgard/watch/daemon.rb +347 -52
  38. data/lib/asgard/watch/declaration.rb +135 -40
  39. data/lib/asgard/watch/dispatcher.rb +61 -10
  40. data/lib/asgard/watch/mailbox.rb +50 -0
  41. data/lib/asgard/watch/reporter.rb +54 -32
  42. data/lib/asgard/watch/spawn.rb +43 -18
  43. data/lib/asgard/watch/state.rb +93 -27
  44. data/lib/asgard/watch/worker.rb +44 -9
  45. data/lib/asgard/watch.rb +4 -11
  46. data/lib/asgard.rb +100 -16
  47. metadata +170 -186
  48. data/.envrc +0 -6
  49. data/.github/workflows/deploy-github-pages.yml +0 -52
  50. data/.loki +0 -39
  51. data/.reek.yml +0 -166
  52. data/.rubocop.yml +0 -163
  53. data/Archspec.rb +0 -24
  54. data/CLAUDE.md +0 -139
  55. data/COMMITS.md +0 -196
  56. data/bin/console +0 -11
  57. data/bin/setup +0 -8
  58. data/doc_tasks.loki +0 -21
  59. data/docs/api.md +0 -368
  60. data/docs/assets/css/custom.css +0 -93
  61. data/docs/assets/images/asgard.jpg +0 -0
  62. data/docs/changelog.md +0 -1
  63. data/docs/dependencies.md +0 -313
  64. data/docs/environment.md +0 -129
  65. data/docs/examples.md +0 -194
  66. data/docs/getting-started.md +0 -181
  67. data/docs/helpers.md +0 -262
  68. data/docs/index.md +0 -87
  69. data/docs/options.md +0 -224
  70. data/docs/schedule.md +0 -106
  71. data/docs/shell.md +0 -237
  72. data/docs/subcommands.md +0 -181
  73. data/docs/task-files.md +0 -407
  74. data/docs/tasks.md +0 -326
  75. data/docs/variables.md +0 -338
  76. data/docs/watch.md +0 -123
  77. data/examples/.env +0 -4
  78. data/examples/.envrc +0 -3
  79. data/examples/.loki +0 -24
  80. data/examples/bad.loki +0 -63
  81. data/examples/concurrent.loki +0 -58
  82. data/examples/confirm.loki +0 -48
  83. data/examples/db_subcommands.loki +0 -74
  84. data/examples/depends_on_block/bad/.loki +0 -51
  85. data/examples/depends_on_block/good/.loki +0 -83
  86. data/examples/do.loki +0 -45
  87. data/examples/env_usage.loki +0 -27
  88. data/examples/kitchen_sink.loki +0 -210
  89. data/examples/server_subcommands.loki +0 -65
  90. data/examples/subdir/.loki +0 -12
  91. data/examples/subdir/import_demo.loki +0 -14
  92. data/examples/subdir/import_up_demo.loki +0 -18
  93. data/examples/watcher_examples/.envrc +0 -3
  94. data/examples/watcher_examples/.loki +0 -54
  95. data/examples/watcher_examples/README.md +0 -112
  96. data/examples/watcher_examples/bin/hello +0 -3
  97. data/examples/watcher_examples/data/records.json +0 -1
  98. data/examples/watcher_examples/docs/drafts/ideas.md +0 -5
  99. data/examples/watcher_examples/docs/index.md +0 -4
  100. data/examples/watcher_examples/lib/greeter.rb +0 -7
  101. data/gem_tasks.loki +0 -51
  102. data/git.loki +0 -13
  103. data/mkdocs.yml +0 -166
  104. data/quality.loki +0 -266
  105. data/quality_rails.loki +0 -47
  106. data/xyzzy.loki +0 -12
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "English"
4
+
3
5
  module Asgard
4
6
  class Base < Thor
5
7
  # Task execution engine: resolves and runs declared dependencies (in
@@ -15,6 +17,76 @@ module Asgard
15
17
  base.extend(ClassMethods)
16
18
  end
17
19
 
20
+ # A finished task's outcome: :failed when its run ended in an error.
21
+ def self.run_state(target, done:, failed:)
22
+ return :failed if failed.key?(target)
23
+
24
+ done.include?(target) ? :done : :free
25
+ end
26
+
27
+ # A group's errors without the ones that only echo another failure:
28
+ # a thread that waited on a failed shared dependency. When nothing
29
+ # else is left, the echoes are all there is to report.
30
+ def self.primary_failures(errors)
31
+ primary = errors.reject { |_, error| error.is_a?(DepFailed) }
32
+ primary.empty? ? errors : primary
33
+ end
34
+
35
+ # A task that is already running further up +chain+ (the tasks this
36
+ # thread is inside, outermost first) and is asked for again can never
37
+ # finish: `def a = invoke(:b)` with `def b = invoke(:a)`. It would
38
+ # wait on itself forever, so name the cycle instead.
39
+ #
40
+ # Each entry, +target+ included, is [class, task name]: a task of the
41
+ # same name in another class is a different task. A subcommand
42
+ # group's `build` runs inside the `build` that dispatches to it, and
43
+ # `jobs restart` runs a project task that may itself be `restart`.
44
+ def self.check_cycle!(chain, target)
45
+ start = chain.index(target)
46
+ return unless start
47
+
48
+ raise Asgard::CircularDependencyError, [*chain[start..], target].map(&:last).join(" -> ")
49
+ end
50
+
51
+ # The options a dependency runs with. They start as the typed task's
52
+ # (+typed+), so an option the dependency does not declare passes
53
+ # through unchanged. The dependency's own defaults (+declared+, class
54
+ # options included) apply over those. Last, each option the user
55
+ # actually gave (+raw+, read against +typed_declared+, the typed
56
+ # task's declarations) reaches the dependency when it declares an
57
+ # option of that name. Words are read only as the typed task means
58
+ # them: a short alias that names something else in the dependency
59
+ # (-f for --file, not --force) never reaches it. A required option
60
+ # of the dependency is not enforced, as it was not before.
61
+ def self.dep_options(declared, typed_declared, raw, typed)
62
+ defaults = Thor::Options.new(declared, {}, false, true).parse([])
63
+ given = given_options(typed_declared, raw).slice(*declared.values.map(&:human_name))
64
+ typed.merge(defaults).merge(given).freeze
65
+ end
66
+
67
+ # Only the options +raw+ spells out, by name, with no defaults filled
68
+ # in: an Array of command-line words read against +declared+, or the
69
+ # Hash a caller passed to new.
70
+ def self.given_options(declared, raw)
71
+ return raw.to_h.transform_keys(&:to_s) unless raw.is_a?(Array)
72
+
73
+ bare = declared.transform_values { without_default(it) }
74
+ Thor::Options.new(bare, {}, false, true).parse(raw).to_h
75
+ end
76
+
77
+ # Whether a method with these +parameters+ (Method#parameters) can be
78
+ # called with +count+ positional arguments.
79
+ def self.accepts?(parameters, count)
80
+ kinds = parameters.map(&:first)
81
+ count >= kinds.count(:req) && (kinds.include?(:rest) || count <= kinds.count { %i[req opt].include?(it) })
82
+ end
83
+
84
+ # A copy of +option+ that parses the same words but has no default.
85
+ def self.without_default(option)
86
+ Thor::Option.new(option.name, type: option.type, aliases: option.aliases, enum: option.enum,
87
+ repeatable: option.repeatable, lazy_default: option.lazy_default)
88
+ end
89
+
18
90
  module ClassMethods
19
91
  def _running
20
92
  @_running ||= Set.new
@@ -28,6 +100,13 @@ module Asgard
28
100
  @_cond ||= Hash.new { |h, k| h[k] = ConditionVariable.new }
29
101
  end
30
102
 
103
+ # Tasks whose body raised or exited, keyed by name, with the error
104
+ # that ended them: a thread that waited on one re-raises instead of
105
+ # running its own body on a prerequisite that never finished.
106
+ def _failed
107
+ @_failed ||= {}
108
+ end
109
+
31
110
  # Completed tasks' return values, keyed by task name — lets a task
32
111
  # already run by one thread hand its result to another thread that
33
112
  # shares the dependency, without either touching `self`.
@@ -46,24 +125,37 @@ module Asgard
46
125
  @_done = Set.new
47
126
  @_cond = Hash.new { |h, k| h[k] = ConditionVariable.new }
48
127
  @_results = {}
128
+ @_failed = {}
49
129
  end
50
130
  end
51
131
  end
52
132
 
53
133
  # Dispatch hook: resolves and runs all deps (in parallel where declared)
54
134
  # before executing the target command.
55
- def invoke_command(command, *)
135
+ def invoke_command(command, args = [])
56
136
  $DEBUG = true if options[:debug]
57
137
  $VERBOSE = true if options[:verbose]
58
138
  target = command.name.to_sym
59
- return cached_result(target) unless acquire_run_token(target)
139
+ Dispatch.check_cycle!(_task_frames.map { [it.owner, it.task] }, [self.class, target])
140
+ case _acquire_run_token(target)
141
+ when :done then return _cached_result(target)
142
+ when :failed then raise DepFailed.new(target, self.class._failed[target])
143
+ end
60
144
 
61
145
  result = nil
146
+ error = nil
62
147
  begin
63
- resolved_deps = run_deps_for(target)
64
- result = with_dep_results(resolved_deps) { command.run(self, *) }
148
+ result = _in_task_frame(target) do
149
+ resolved_deps = _callable_with?(target, args) ? _run_deps_for(target) : {}
150
+ _with_dep_results(resolved_deps) { command.run(self, args) }
151
+ end
152
+ rescue Exception => e # rubocop:disable Lint/RescueException -- an exit or interrupt ends the task too
153
+ # Captured here, not read from $! in an ensure: $! still holds a
154
+ # caller's exception when this runs inside its rescue block.
155
+ error = e
156
+ raise
65
157
  ensure
66
- signal_done(target, result)
158
+ _signal_done(target, result, error)
67
159
  end
68
160
  result
69
161
  end
@@ -78,9 +170,41 @@ module Asgard
78
170
  dep_results[task.to_sym]
79
171
  end
80
172
 
173
+ # One running task, from its dependencies through its body: the class
174
+ # it belongs to, its name and how many background jobs it has started
175
+ # so far. Frames live on
176
+ # a thread-local stack, so a task running as a dependency in a
177
+ # parallel stage sees itself, not the task the user typed. A parallel
178
+ # stage's thread starts with a copy of its parent's stack, which is
179
+ # how a cycle through that stage is still seen (see check_cycle!).
180
+ TaskFrame = Struct.new(:owner, :task, :jobs)
181
+
182
+ # The task whose body is running on this thread, or nil outside one
183
+ # (a helper called at .loki top level).
184
+ def current_task = _task_frames.last&.task
185
+
186
+ # The next sequence number for a background job of the current task:
187
+ # 1 on the first call of each run of the body, then 2, 3, ...
188
+ def _next_job_sequence
189
+ frame = _task_frames.last
190
+ raise Asgard::Error, "no task is running on this thread" unless frame
191
+
192
+ frame.jobs += 1
193
+ end
194
+
81
195
  private
82
196
 
83
- def with_dep_results(results)
197
+ def _task_frames = Thread.current[:asgard_task_frames] ||= []
198
+
199
+ def _in_task_frame(task)
200
+ frames = _task_frames
201
+ frames.push(TaskFrame.new(self.class, task, 0))
202
+ yield
203
+ ensure
204
+ frames.pop
205
+ end
206
+
207
+ def _with_dep_results(results)
84
208
  thread = Thread.current
85
209
  previous = thread[:asgard_dep_results]
86
210
  thread[:asgard_dep_results] = results
@@ -89,71 +213,187 @@ module Asgard
89
213
  thread[:asgard_dep_results] = previous
90
214
  end
91
215
 
92
- def cached_result(target)
216
+ def _cached_result(target)
93
217
  klass = self.class
94
218
  klass._ran_mutex.synchronize { klass._results[target] }
95
219
  end
96
220
 
97
- def acquire_run_token(target)
221
+ # :run when this thread is to run +target+, :done when another
222
+ # already ran it, :failed when that run raised or exited. A thread
223
+ # that finds it running waits for the outcome.
224
+ def _acquire_run_token(target)
98
225
  klass = self.class
99
226
  mutex = klass._ran_mutex
100
227
  done = klass._done
101
228
  running = klass._running
102
229
 
103
230
  mutex.synchronize do
104
- if done.include?(target)
105
- false
106
- elsif running.include?(target)
231
+ if running.include?(target) && !done.include?(target)
107
232
  klass._cond[target].wait(mutex) until done.include?(target)
108
- false
109
- else
110
- running.add(target)
111
- true
112
233
  end
234
+ next Dispatch.run_state(target, done:, failed: klass._failed) if done.include?(target)
235
+
236
+ running.add(target)
237
+ :run
113
238
  end
114
239
  end
115
240
 
116
- def run_deps_for(target)
241
+ # False when +args+ cannot be the task's arguments. Its dependencies
242
+ # are then skipped, so the usage error Thor prints for the call is
243
+ # all that happens.
244
+ def _callable_with?(target, args)
245
+ !respond_to?(target, true) || Dispatch.accepts?(method(target).parameters, args.size)
246
+ end
247
+
248
+ def _run_deps_for(target)
117
249
  stages = self.class._deps[target]
118
250
  return {} unless stages&.any?
119
251
 
120
- stages.each_with_object({}) { |group, acc| acc.merge!(run_dep_group(group)) }
252
+ stages.each_with_object({}) { |group, acc| acc.merge!(_run_dep_group(group)) }
121
253
  end
122
254
 
123
- def run_dep_group(group)
124
- return { group.first => run_dep(group.first) } unless group.size > 1
255
+ def _run_dep_group(group)
256
+ return { group.first => _run_dep(group.first) } unless group.size > 1
125
257
 
126
- threads = group.map { |task| [task, Thread.new { run_dep(task) }] }
127
- errors = []
258
+ threads = group.map { |task| [task, _dep_thread(task)] }
259
+ errors = {}
128
260
  results = {}
261
+ # Join every thread before raising, so one failure never ends the
262
+ # process while the other tasks' subprocesses run on, orphaned.
129
263
  threads.each do |task, t|
130
264
  results[task] = t.value
131
- rescue => e
132
- errors << e
265
+ rescue StandardError, ScriptError => e
266
+ errors[task] = e
133
267
  end
134
268
 
135
- if errors.size == 1
136
- raise errors.first
137
- elsif errors.any?
138
- errors.each { |e| warn "asgard: #{e.message}" }
139
- raise Asgard::Error, "#{errors.size} parallel dependencies failed"
140
- end
269
+ errors = Dispatch.primary_failures(errors)
270
+ _raise_dep_failure(errors.values.first) if errors.size == 1
271
+ _raise_group_failure(errors) if errors.any?
141
272
 
142
273
  results
143
274
  end
144
275
 
145
- def signal_done(target, result)
276
+ # A SystemExit that ended a dependency thread (a failing `sh`, an
277
+ # `abort`), carried out of the thread as an ordinary error. Ruby
278
+ # re-raises an unhandled SystemExit from any thread in the main
279
+ # thread, which would end the process in the middle of the join.
280
+ class DepExit < StandardError
281
+ attr_reader :status
282
+
283
+ def initialize(status)
284
+ @status = status
285
+ super("exit #{status}")
286
+ end
287
+ end
288
+
289
+ # Raised in a thread that waited on +task+ when +task+ failed. Its
290
+ # +error+ is the failure itself, which some other thread reports, so
291
+ # the joiner counts only that one (see primary_failures).
292
+ class DepFailed < StandardError
293
+ attr_reader :task, :error
294
+
295
+ def initialize(task, error)
296
+ @task = task
297
+ @error = error
298
+ super("dependency '#{task}' failed")
299
+ end
300
+ end
301
+
302
+ # Ruby's own report would print the full backtrace to stderr before
303
+ # the error reaches asgard's handler; the joiner re-raises it anyway.
304
+ # Each parallel task runs on its own instance (same options), so two
305
+ # tasks in one stage never race on an instance variable; results
306
+ # pass between tasks through dep_result, not through self.
307
+ def _dep_thread(task)
308
+ instance = _parallel_instance
309
+ frames = _task_frames.dup
310
+ Thread.new do
311
+ thread = Thread.current
312
+ thread.report_on_exception = false
313
+ thread[:asgard_task_frames] = frames
314
+ instance.__send__(:_run_dep, task)
315
+ rescue SystemExit => e
316
+ raise DepExit, e.status
317
+ end
318
+ end
319
+
320
+ # Built as Thor built this instance: the same command line and the
321
+ # same config, which names the typed command. Thor then reads the
322
+ # words against that command's options, as it did the first time,
323
+ # so check_unknown_options! knows them. The task the copy runs reads
324
+ # its own options from the same words (see dep_options).
325
+ def _parallel_instance
326
+ config = _initializer_config
327
+ typed = config[:current_command]
328
+ config = config.merge(command_options: typed.options) if typed
329
+ instance = self.class.new([], _raw_options, config)
330
+ instance.options = options
331
+ instance
332
+ end
333
+
334
+ # The options this instance was created with, before parsing: the
335
+ # command line's words, or the Hash a caller passed to new.
336
+ def _raw_options = @_initializer[1]
337
+
338
+ # The config Thor created this instance with; its :current_command
339
+ # is the task that was typed (or invoked).
340
+ def _initializer_config = @_initializer[2] || {}
341
+
342
+ # What the command line's words are read against: the class options
343
+ # plus the typed task's own.
344
+ def _typed_declared
345
+ typed = _initializer_config[:current_command]
346
+ declared = self.class.class_options
347
+ typed ? declared.merge(typed.options) : declared
348
+ end
349
+
350
+ # Runs the block with +opts+ as this instance's options.
351
+ def _with_options(opts)
352
+ previous = options
353
+ self.options = opts
354
+ yield
355
+ ensure
356
+ self.options = previous
357
+ end
358
+
359
+ def _dep_options_for(command)
360
+ Dispatch.dep_options(self.class.class_options.merge(command.options), _typed_declared, _raw_options, options)
361
+ end
362
+
363
+ # One failure: a dependency that exited ends asgard with its status,
364
+ # as it would have on its own; anything else propagates unchanged.
365
+ def _raise_dep_failure(error)
366
+ error = error.error while error.is_a?(DepFailed) && error.error
367
+ case error
368
+ when DepExit, SystemExit then exit(error.status)
369
+ else raise(error)
370
+ end
371
+ end
372
+
373
+ # Every script in the group stopped because asgard was signalled:
374
+ # that is the one failure, so it exits as asgard would on its own.
375
+ def _raise_group_failure(errors)
376
+ signalled = Shell::Children.exit_status
377
+ exit(signalled) if signalled
378
+ errors.each { |task, e| $stderr.puts "asgard: dependency '#{task}' failed: #{_describe_failure(e)}" } # rubocop:disable Style/StderrPuts
379
+ raise Asgard::Error, "parallel dependencies failed: #{errors.keys.join(', ')}"
380
+ end
381
+
382
+ def _describe_failure(error) = error.is_a?(DepExit) ? error.message : "#{error.class}: #{error.message}"
383
+
384
+ def _signal_done(target, result, error = nil)
146
385
  klass = self.class
147
386
  klass._ran_mutex.synchronize do
148
387
  klass._done.add(target)
149
388
  klass._results[target] = result
389
+ klass._failed[target] = error if error
150
390
  klass._cond[target].broadcast
151
391
  end
152
392
  end
153
393
 
154
- def run_dep(task)
394
+ def _run_dep(task)
155
395
  command = self.class.all_commands[task.to_s]
156
- invoke_command(command) if command
396
+ _with_options(_dep_options_for(command)) { invoke_command(command) } if command
157
397
  end
158
398
  end
159
399
  end
@@ -7,13 +7,16 @@ module Asgard
7
7
  # --doctor`) uses to detect a silently-overridden `def`, same file or
8
8
  # across files.
9
9
  module Registry
10
- def subclasses
11
- @subclasses ||= []
10
+ # Every subclass of Asgard::Base, at any depth, in definition order.
11
+ # Not `subclasses`: that is Ruby's own Class#subclasses (direct
12
+ # subclasses only), which a .loki may well call.
13
+ def _asgard_subclasses
14
+ @_asgard_subclasses ||= []
12
15
  end
13
16
 
14
17
  def inherited(subclass)
15
18
  super
16
- Asgard::Base.subclasses << subclass
19
+ Asgard::Base._asgard_subclasses << subclass
17
20
  subclass.instance_variable_set(:@_deps, {})
18
21
  subclass.instance_variable_set(:@_method_log, Hash.new { |h, k| h[k] = [] })
19
22
  subclass.instance_variable_set(:@_pending_deps, [])
@@ -23,6 +26,7 @@ module Asgard
23
26
  subclass.instance_variable_set(:@_done, Set.new)
24
27
  subclass.instance_variable_set(:@_cond, Hash.new { |h, k| h[k] = ConditionVariable.new })
25
28
  subclass.instance_variable_set(:@_ran_mutex, Mutex.new)
29
+ subclass.instance_variable_set(:@_failed, {})
26
30
  end
27
31
 
28
32
  # Every source_location a method name has ever been defined at, in
@@ -38,7 +38,13 @@ module Asgard
38
38
  Dotenv.load(path) if File.exist?(path)
39
39
  end
40
40
 
41
+ # A reserved name is refused before anything is defined, at the .loki
42
+ # line that called helper rather than at the define_method below.
41
43
  def helper(name, &)
44
+ if _reserved_name?(name.to_sym)
45
+ here = caller_locations(1, 1).first
46
+ _raise_reserved_name!(name, here.path, here.lineno)
47
+ end
42
48
  define_singleton_method(name, &)
43
49
  no_commands { private define_method(name) { |*args, **kwargs, &blk| self.class.send(name, *args, **kwargs, &blk) } }
44
50
  end
data/lib/asgard/base.rb CHANGED
@@ -17,11 +17,45 @@ module Asgard
17
17
  extend TaskDSL
18
18
  include Dispatch
19
19
 
20
+ THOR_LIB = File.dirname(Thor.method(:subcommand).source_location.first)
21
+ ASGARD_LIB = File.expand_path("..", __dir__)
22
+
23
+ # Names Thor's machinery relies on: its reserved words plus the readers
24
+ # dispatch calls on every instance, which Thor itself does not guard.
25
+ # A task or helper by one of these names breaks every command, with
26
+ # nothing in the failure pointing at the cause.
27
+ RESERVED_NAMES = (Thor::THOR_RESERVED_WORDS + %w[args parent_options]).map(&:to_sym).freeze
28
+
29
+ # The helpers lib/asgard/kernel_methods.rb adds to Kernel.
30
+ KERNEL_HELPERS = %i[debug? verbose? env changes loki_up import import_up].freeze
31
+
32
+ # Asgard's own helpers a task body calls (sh, env, dep_result, ...)
33
+ # and the methods dispatch runs every task through. A task or helper
34
+ # by one of these names would silently replace it.
35
+ ASGARD_HELPERS = [Shell, Dispatch].flat_map { |mod| mod.instance_methods(false) + mod.private_instance_methods(false) }
36
+ .concat(KERNEL_HELPERS).uniq.freeze
37
+
20
38
  class << self
21
39
  # A usage error (missing argument, unknown command or option) exits 1,
22
40
  # so CI and `asgard do` sequences see the failure. Thor's default is 0.
23
41
  def exit_on_failure? = true
24
42
 
43
+ # A subcommand group's help lists only the group's own commands. The
44
+ # tasks it inherits from Tasks still run, but Thor would list them
45
+ # too, under the class's default namespace (doc_commands for
46
+ # DocCommands), burying the group's own.
47
+ def printable_commands(all = true, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
48
+ super(all && !subcommand, subcommand)
49
+ end
50
+
51
+ # `subcommand "doc", DocCommands` names the group doc, so `tree` shows
52
+ # it as doc rather than Thor's doc_commands. A group that set its own
53
+ # namespace keeps it.
54
+ def subcommand(name, klass)
55
+ klass.namespace(name) if klass.namespace == Thor::Util.namespace_from_thor_class(klass)
56
+ super
57
+ end
58
+
25
59
  def header(text = nil)
26
60
  return @_header if text.nil?
27
61
  (@_header ||= []) << text
@@ -32,22 +66,126 @@ module Asgard
32
66
  (@_footer ||= []).unshift(text)
33
67
  end
34
68
 
69
+ # A method Thor generates (a `subcommand` dispatcher, a subcommand
70
+ # class's string-eval'd `help`) reports a source_location inside Thor.
71
+ # Credit it to the first caller frame outside Thor and asgard — the
72
+ # .loki line that called `subcommand` — so Doctor lists it there.
73
+ def definition_site(loc, callers)
74
+ return loc unless thor_generated?(loc.first)
75
+
76
+ site = callers.find { |frame| user_frame?(frame.path) }
77
+ site ? [site.path, site.lineno] : loc
78
+ end
79
+
80
+ def thor_generated?(path)
81
+ path.start_with?("(eval", THOR_LIB)
82
+ end
83
+
84
+ def user_frame?(path)
85
+ !thor_generated?(path) && !path.start_with?(ASGARD_LIB)
86
+ end
87
+
88
+ HIDDEN_DESC = "(hidden task: defined without a desc)"
89
+
90
+ # A public method a .loki defines without a desc is a hidden task:
91
+ # it runs from the command line and as a dependency, and help leaves
92
+ # it out. Not one: a method that already has a desc pending, anything
93
+ # inside no_commands (helpers), non-public methods, the gem's own
94
+ # _-prefixed names, and a name Thor already has a command for (help).
95
+ # Nor a method every object already has (to_s, inspect,
96
+ # respond_to_missing?): see object_method?.
97
+ def implicit_hidden_task?(method_name)
98
+ name = method_name.to_s
99
+ !@usage && !no_commands? && !name.start_with?("_") && !object_method?(method_name) &&
100
+ public_method_defined?(method_name) && !all_commands.key?(name)
101
+ end
102
+
103
+ # A method Thor (and so Object) already defines: a public one
104
+ # (to_s, inspect, display), or a private one that is not a Kernel
105
+ # module function (method_missing, respond_to_missing?). Kernel's
106
+ # module functions (test, format, system) stay free to be task names.
107
+ def object_method?(method_name)
108
+ Thor.public_method_defined?(method_name) ||
109
+ (Thor.private_method_defined?(method_name) && !Kernel.respond_to?(method_name))
110
+ end
111
+
112
+ # The task `asgard help NAME` describes: a built-in group's mapped
113
+ # name ("jobs") is its registered subcommand ("_jobs"); anything else
114
+ # is NAME unchanged.
115
+ def help_target(command)
116
+ mapped = map[command.to_s]&.to_s
117
+ subcommands.include?(mapped) ? mapped : command
118
+ end
119
+
120
+ def _check_reserved_name!(method_name)
121
+ return unless _reserved_name?(method_name)
122
+
123
+ file, line = instance_method(method_name).source_location
124
+ remove_method(method_name) # leave the original in place, so the class still dispatches
125
+ _raise_reserved_name!(method_name, file, line)
126
+ end
127
+
128
+ # Whether +name+ is one a task or helper cannot take.
129
+ def _reserved_name?(name) = RESERVED_NAMES.include?(name) || ASGARD_HELPERS.include?(name)
130
+
131
+ # Raises the reserved-name error for +name+, defined at +file+:+line+.
132
+ def _raise_reserved_name!(name, file, line)
133
+ what = RESERVED_NAMES.include?(name) ? "a name Thor reserves" : "an asgard helper"
134
+ raise Asgard::Error, "'#{name}' at #{file}:#{line} is #{what} and cannot be a task or helper; rename it"
135
+ end
136
+
137
+ # `private def helper = ...` makes the method private only after
138
+ # method_added has seen it public and made it a hidden task, and Ruby
139
+ # has no hook for the change (overriding `private` would break its
140
+ # no-argument form in every subclass). So whenever the command table
141
+ # is read (dispatch, help, doctor), a hidden task whose method is no
142
+ # longer public is dropped from it.
143
+ def all_commands
144
+ super.tap { _drop_non_public_hidden_tasks(it) }
145
+ end
146
+
147
+ # Removes from +all+ (and this class's own table) each hidden task,
148
+ # one defined without a desc, whose method is private or protected,
149
+ # with any depends_on attached to it.
150
+ def _drop_non_public_hidden_tasks(all)
151
+ stale = all.select { |name, command| command.description == HIDDEN_DESC && !public_method_defined?(name) }
152
+ stale.each_key do |name|
153
+ all.delete(name)
154
+ commands.delete(name)
155
+ _deps.delete(name.to_sym)
156
+ end
157
+ end
158
+
159
+ # A redefined to_s or inspect with no desc of its own: not a task, and
160
+ # not worth Thor's "without usage or description" warning either.
161
+ def plain_object_method?(method_name) = !@usage && !@_pending_single_desc && object_method?(method_name)
162
+
163
+ # Turns a pending single-argument `desc "text"` into Thor's desc for
164
+ # the method just defined.
165
+ def _apply_pending_desc(name)
166
+ return unless @_pending_single_desc && !no_commands?
167
+
168
+ pending_desc = @_pending_single_desc
169
+ pending_opts = @_pending_single_desc_opts || {}
170
+ @_pending_single_desc = nil
171
+ @_pending_single_desc_opts = nil
172
+ desc(name, pending_desc, pending_opts)
173
+ end
174
+
35
175
  def method_added(method_name)
176
+ _check_reserved_name!(method_name)
177
+ return no_commands { super } if plain_object_method?(method_name)
178
+
36
179
  name = method_name.to_s
37
180
  private_method = name.start_with?("_")
38
181
 
39
182
  unless private_method
40
183
  loc = instance_method(method_name).source_location
41
- _method_log[method_name] << loc if loc
184
+ _method_log[method_name] << definition_site(loc, caller_locations) if loc
42
185
  end
43
186
 
44
- if @_pending_single_desc && !no_commands?
45
- pending_desc = @_pending_single_desc
46
- pending_opts = @_pending_single_desc_opts || {}
47
- @_pending_single_desc = nil
48
- @_pending_single_desc_opts = nil
49
- desc(name, pending_desc, pending_opts)
50
- end
187
+ _apply_pending_desc(name)
188
+ desc(name, HIDDEN_DESC, hide: true) if implicit_hidden_task?(method_name)
51
189
 
52
190
  return super unless @usage
53
191
 
@@ -70,7 +208,7 @@ module Asgard
70
208
 
71
209
  say header_text.join("\n\n") if header_text && top_level
72
210
  say "\n"
73
- super
211
+ super(klass.help_target(command), subcommand)
74
212
  say footer_text.join("\n\n") if footer_text && top_level
75
213
  end
76
214
 
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Asgard
4
+ # What `schedule` and `watch` share: a registry of declared entries,
5
+ # keyed by entry name.
6
+ module Declarations
7
+ module_function
8
+
9
+ # Stores +spec+ (a Hash with a :name) in +declarations+ and returns it.
10
+ # An identical entry already there is a no-op (a .loki file loaded
11
+ # twice); a different one under the same name is an error that names
12
+ # +kind+ ("schedule", "watch").
13
+ def record(declarations, spec, kind)
14
+ name = spec[:name]
15
+ taken = declarations[name]
16
+ raise ArgumentError, "#{kind}: #{name.inspect} is already declared; give one a distinct as: name" if taken && taken != spec
17
+
18
+ declarations[name] = spec
19
+ end
20
+ end
21
+ end
@@ -55,9 +55,13 @@ module Asgard
55
55
  end
56
56
  end
57
57
 
58
+ def problem_count
59
+ @findings.count { |finding| finding.level == :error } + override_count
60
+ end
61
+
58
62
  def summary_line
59
63
  by_level = @findings.group_by(&:level)
60
- errors = (by_level[:error]&.size || 0) + override_count
64
+ errors = problem_count
61
65
  warns = by_level[:warn]&.size || 0
62
66
  return colorize(32, "No problems found.") if errors.zero? && warns.zero?
63
67
  return colorize(33, "No problems found (#{warns} warning(s)).") if errors.zero?