asgard 0.6.0 → 0.6.2

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0ce55713997e41bcc3531ce3b34765e872184ab435aaa310eecc45625240c840
4
- data.tar.gz: 0913ae51128056486619cf7655479dd28c6298300699ee307e6ec88a0c5e6d6d
3
+ metadata.gz: 6d009f656e6d58b451c19ad7e9dde32c13a4e37c2943dace9f6afc018c17934d
4
+ data.tar.gz: a843940da659cf7e77912b32efe262547d2ac85e4ce09f9dd54dcb0104c65b19
5
5
  SHA512:
6
- metadata.gz: 416c0a47d231bc39c1b14351d48edaa75a00538f3ee5a9f6e0b2aeb78ca63badc72e77f1d6010f4e50e7235d22f436e93ae5b6c7a9719851ca82bfe43a8338bb
7
- data.tar.gz: 7426f8fdd9fc2f56655f2584685b91634890cc8ccb84ef0c0a01ec25d8e7085770f2e0ce5fbedfe6da89ac01c552b938b5dc87fa0efc9ec5242acbac1f963348
6
+ metadata.gz: af6cf9020773314672e8dd93c1a39654fbae24fa519b049babf2843435b48a974052a651efb595066d14addc99cb31e0936f22f7630d20a1b3785a16593698d0
7
+ data.tar.gz: ef3058d0afc35d29007ce8e34bbead12669b06d08af83a1cd50865dc40cf5ff5a5639c69928d024af703ff33b006f5c8298e08d808ea02a311cece11ad2c0c8c
data/CHANGELOG.md CHANGED
@@ -5,6 +5,163 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [0.6.2] - 2026-11-18
11
+
12
+ A patch release of CLI fixes: leading `--debug` and `--verbose` in every
13
+ form, `TASK --help`, and clearer messages for an unknown option, a
14
+ mistyped `jobs` subcommand and a `default_task` that is not a task. No
15
+ `.loki` file needs to change, and nothing that worked in 0.6.1 breaks.
16
+
17
+ ### Changed
18
+
19
+ - **An unknown leading option is named as an option**: `asgard --nope`
20
+ now says `asgard: unknown option '--nope'; see asgard help` instead of
21
+ `Could not find command "__nope".` Only the message changes; it still
22
+ exits 1, so this is not a breaking change.
23
+ - **A bad `schedule ... every:` says what it accepts and what it got**:
24
+ the message no longer suggests `3.minutes`, which fails without
25
+ ActiveSupport, and now ends with the value given, e.g. `got 90.0`.
26
+ ([#46](https://github.com/MadBomber/asgard/issues/46))
27
+ - **`asgard TASK --help` shows the task's help**: `TASK --help` and
28
+ `TASK -h` now work like `asgard help TASK`, instead of running the task
29
+ with `--help` as its argument or failing with "was called with
30
+ arguments". ([#43](https://github.com/MadBomber/asgard/issues/43))
31
+
32
+ ### Fixed
33
+
34
+ - **A leading `--debug` or `--verbose` keeps the list commands machine-wide**:
35
+ `asgard --debug jobs list`, `schedule list` and `watcher list` now run
36
+ from a directory with no `.loki` above it, instead of stopping with "no
37
+ .loki file found".
38
+ - **Every form of a leading `--debug` or `--verbose` runs the task named
39
+ after it**: `asgard --debug=true build`, `--no-debug` and `--skip-verbose`
40
+ now move behind the task name like a bare `--debug`, instead of running
41
+ the default task with `build` as its argument or printing its usage.
42
+ A leading flag also reaches a task defined without a `desc` or with
43
+ `hide: true`, and a task named with dashes (`deploy-app` for
44
+ `deploy_app`). ([#38](https://github.com/MadBomber/asgard/issues/38))
45
+ - **An empty word after a leading flag reaches the default task**:
46
+ `asgard --verbose ''` runs the default task with `""` as its argument,
47
+ as it did before 0.6.1, instead of failing as an ambiguous command that
48
+ listed the gem's internal `_jobs`, `_schedule` and `_watcher` names.
49
+ - **The README's opening callout renders as a note on GitHub**: it used
50
+ `[!INFO]`, which GitHub does not recognise, and now uses `[!NOTE]`.
51
+ ([#45](https://github.com/MadBomber/asgard/issues/45))
52
+ - **The test suite passes with `RUBYOPT=-w` or `ASGARD_TRACE` set**: the
53
+ tests that run `bin/asgard` as a child process no longer pass on the
54
+ developer's trace setting or warning level.
55
+ ([#48](https://github.com/MadBomber/asgard/issues/48))
56
+ - **`watcher.log` no longer opens with Ruby's experimental-Ractor warning**:
57
+ the watcher silences that one warning while it starts its workers, so
58
+ `watcher start` logs and `watcher run` output begin with real entries.
59
+ ([#44](https://github.com/MadBomber/asgard/issues/44))
60
+ - **`--doctor` says why a task is hidden**: a task described with
61
+ `hide: true` is listed as `hidden (hide: true; not shown by help)`
62
+ instead of `hidden (no desc; ...)`, which now marks only desc-less tasks.
63
+ ([#47](https://github.com/MadBomber/asgard/issues/47))
64
+ - **`--doctor` prints no colour codes when piped or with `NO_COLOR` set**:
65
+ it colours its lines only on a terminal, as the `list` tables do.
66
+ ([#50](https://github.com/MadBomber/asgard/issues/50))
67
+ - **A `default_task` that names no task is reported as such**: plain
68
+ `asgard` (or `asgard --debug`) now says `asgard: default_task :nope (set
69
+ at .loki:2) is not a task` instead of `Could not find command "".`
70
+ ([#51](https://github.com/MadBomber/asgard/issues/51))
71
+ - **A mistyped `jobs` subcommand is named**: `asgard jobs stpo api` now
72
+ says `Could not find command "stpo".` with a "Did you mean?" hint, as
73
+ `schedule` and `watcher` do, instead of reporting arguments to `jobs list`.
74
+ ([#52](https://github.com/MadBomber/asgard/issues/52))
75
+
76
+ ## [0.6.1] - 2026-11-14
77
+
78
+ Two changes can break a script that runs asgard: `--doctor` exits 1 when
79
+ it reports problems, and `--debug` or `--verbose` before a task name now
80
+ runs that task. See
81
+ [Breaking Changes](https://madbomber.github.io/asgard/breaking-changes/#061).
82
+
83
+ ### Added
84
+
85
+ - **A DSL word outside `class Tasks` gets a hint**: `desc` or `depends_on` at the top level of a `.loki` now ends the load-error line with a reminder that they go inside `class Tasks ... end`.
86
+ - **The gem links its docs site and issue tracker**: the gemspec sets
87
+ `documentation_uri` and `bug_tracker_uri`, so the RubyGems page links to
88
+ [the docs site](https://madbomber.github.io/asgard) and the
89
+ [GitHub issues](https://github.com/MadBomber/asgard/issues).
90
+ - **The docs site serves `llms.txt`**:
91
+ [/llms.txt](https://madbomber.github.io/asgard/llms.txt) lists every docs
92
+ page with a one-line description, in the [llms.txt](https://llmstxt.org)
93
+ format.
94
+ - **`truncate_log` shortens logs in place**: `asgard schedule truncate_log
95
+ [NAME]`, `asgard watcher truncate_log` and `asgard jobs truncate_log [NAME]`
96
+ keep the last `--lines M` lines (default 1000; `0` empties the log), rewriting
97
+ the file in place so a running writer keeps appending to it. A truncate
98
+ cut short by Ctrl-C, a signal or a failed write still leaves a whole log.
99
+ `--dry-run` (`-n`) reports what would be removed without changing anything.
100
+ - **Two new guides in the docs**: [A dependency with
101
+ arguments](https://madbomber.github.io/asgard/dependencies/#a-dependency-with-arguments)
102
+ shows how to give a dependency the arguments it needs, and
103
+ [`examples/simple_flow`](https://madbomber.github.io/asgard/examples/#simple_flow)
104
+ runs a fan-out and fan-in of steps inside one task with
105
+ [simple_flow](https://github.com/MadBomber/simple_flow).
106
+
107
+ ### Changed
108
+
109
+ - **BREAKING: `asgard --doctor` exits 1 when it reports problems**,
110
+ including overridden task definitions, so scripts and CI can use it as a
111
+ check. Warnings alone still exit 0. A script that ran `--doctor` and
112
+ ignored what it reported now fails on those problems
113
+ ([#13](https://github.com/MadBomber/asgard/issues/13)).
114
+ - **BREAKING: `--debug` and `--verbose` before a task name run that task**:
115
+ `asgard --verbose build` is now `asgard build --verbose`. It used to print
116
+ the help for `build`, or, in a project with a `default_task`, run the
117
+ default task with `build` as its argument. In front of a word that is not a
118
+ task the flags still run the default task with that word
119
+ ([#27](https://github.com/MadBomber/asgard/issues/27)).
120
+ - **The repository's own task files load from a shared checkout**: the root
121
+ `.loki` runs `import_up "dev/.loki"` to load the quality, gem, git and docs
122
+ tasks of [MadBomber/dev](https://github.com/MadBomber/dev), and the local
123
+ `test_check.loki` replaces two of them with asgard's own test runner.
124
+ `xyzzy.loki` is gone; those replacements are now the worked example of an
125
+ override in the docs. `quality_rails.loki` is gone too; conditional imports
126
+ stay in the docs as an example. Without `dev` cloned beside asgard, the
127
+ root `.loki` aborts with a message naming the repository to clone. The gem
128
+ itself is unchanged.
129
+ - **One parent-directory walk**: `loki_up`, `import_up` and `--doctor`'s
130
+ marker search use `Pathname#ascend` instead of three hand-rolled loops; what
131
+ they find is unchanged ([#19](https://github.com/MadBomber/asgard/issues/19)).
132
+ - **Schedule and watcher take the project root from `Asgard.project_root`**,
133
+ as jobs already did, so all three act on the same project
134
+ ([#26](https://github.com/MadBomber/asgard/issues/26)).
135
+ - **CI runs on Node 24 actions**: the workflows use `actions/checkout@v7`
136
+ and `actions/setup-python@v7`, replacing the deprecated Node 20 majors
137
+ ([#29](https://github.com/MadBomber/asgard/issues/29)).
138
+ - **Schedule log directories are private**: `asgard schedule install`
139
+ creates the log directory 0700 (and tightens an existing one), as the
140
+ watch and jobs state directories already are.
141
+
142
+ ### Fixed
143
+
144
+ - **A task called with arguments it cannot take runs nothing**: the usage
145
+ error is reported before the task's dependencies run, not after them
146
+ ([#27](https://github.com/MadBomber/asgard/issues/27)).
147
+ - **A `helper` with a reserved name is reported at its `.loki` line**, not at
148
+ asgard's own `task_dsl.rb`, and is refused before anything is defined
149
+ ([#25](https://github.com/MadBomber/asgard/issues/25)).
150
+ - **`bin/console` and the `console` task load on Ruby 4**: the Gemfile lists
151
+ `irb`, which is no longer a default gem ([#28](https://github.com/MadBomber/asgard/issues/28)).
152
+ - **`truncate_log NAME` on an entry with no log yet is not an error**: a declared schedule or recorded job that has not written its log says `NAME has no log yet (PATH); nothing to truncate` and exits 0 ([#18](https://github.com/MadBomber/asgard/issues/18)).
153
+ - **A background job started right after it ended starts again**, instead
154
+ of being reported as already running while its old shell exits.
155
+ - **`asgard --doctor` reports a `.loki` that calls `exit` or `abort`** as a
156
+ load failure instead of exiting with no report.
157
+ - **Dependency errors name the task(s) that declared them**: an undefined
158
+ dependency ([#14](https://github.com/MadBomber/asgard/issues/14)) and a
159
+ dependency that takes required arguments both end with
160
+ `(needed by ci, release)`.
161
+ - **The test suite passes with no locale set**: output read back from a
162
+ child `asgard` is tagged UTF-8, so a shell without `LANG` or `LC_ALL` no
163
+ longer fails the tests that compare it.
164
+
8
165
  ## [0.6.0] - 2026-10-31
9
166
 
10
167
  Upgrading from 0.5.x? Read
@@ -462,6 +619,9 @@ reinstalled after.
462
619
  - 100% test coverage enforced via SimpleCov (95% minimum threshold)
463
620
  - Quality task in `.loki` runs flog after tests
464
621
 
622
+ [Unreleased]: https://github.com/MadBomber/asgard/compare/v0.6.2...HEAD
623
+ [0.6.2]: https://github.com/MadBomber/asgard/compare/v0.6.1...v0.6.2
624
+ [0.6.1]: https://github.com/MadBomber/asgard/compare/v0.6.0...v0.6.1
465
625
  [0.6.0]: https://github.com/MadBomber/asgard/compare/v0.5.1...v0.6.0
466
626
  [0.5.1]: https://github.com/MadBomber/asgard/compare/v0.4.1...v0.5.1
467
627
  [0.4.1]: https://github.com/MadBomber/asgard/compare/v0.4.0...v0.4.1
data/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Asgard
2
2
 
3
- > [!INFO]
3
+ > [!NOTE]
4
4
  > See the [CHANGELOG](CHANGELOG.md) for the latest changes. The [examples directory](examples/) contains working `.loki` files demonstrating the full feature set.
5
5
 
6
6
  > [!WARNING]
@@ -659,6 +659,7 @@ asgard schedule stop NAME # stop one entry (persists across reboots and ins
659
659
  asgard schedule start NAME # start a stopped entry, or install just this one
660
660
  asgard schedule trigger NAME # run an installed entry now
661
661
  asgard schedule log NAME [-f] # print (or follow) the entry's log
662
+ asgard schedule truncate_log [NAME] --lines M # keep the last M lines of the log (default 1000; no NAME: all; -n: dry run)
662
663
  asgard schedule remove [NAME] # remove one entry, or all of this project's
663
664
  asgard schedule prune [-n] # remove every project's entries whose directory is gone (-n: list only)
664
665
  ```
@@ -699,6 +700,7 @@ asgard watcher stop --force # stop it and end any running task
699
700
  asgard watcher list # watches, daemon state, each entry's last run (--all: every project's)
700
701
  asgard watcher preview # the command and environment each watch would run
701
702
  asgard watcher log [-f] # print (or follow) the watcher's log
703
+ asgard watcher truncate_log --lines M # keep the last M lines (default 1000) of watcher.log and watcher.log.1
702
704
  ```
703
705
 
704
706
  Each trigger runs `asgard <task>` from the project root with a fixed
@@ -736,6 +738,7 @@ end
736
738
  asgard jobs list # running, exited with a status, or gone (--all: every project's)
737
739
  asgard jobs stop servers # by job name, or by task and the tasks it depends on
738
740
  asgard jobs log api -f # print (or follow) one job's log
741
+ asgard jobs truncate_log [NAME] --lines M # keep the last M lines of the log (default 1000; no NAME: all; -n: dry run)
739
742
  asgard jobs restart api # stop it, then run its owning task again
740
743
  asgard jobs clean # forget every job that is no longer running
741
744
  ```
@@ -836,7 +839,7 @@ end
836
839
 
837
840
  ## Tips
838
841
 
839
- - **Start from working files.** The task files at this repository's root (`.loki`, `quality.loki`, `gem_tasks.loki`, `git.loki`, `doc_tasks.loki`) are a real multi-file project: quality gates that return `:pass` or `:fail`, a background job, a subcommand group, a `helper` feeding the `header`, and a deliberate override for `--doctor`. Copy what fits.
842
+ - **Start from working files.** The task files at this repository's root (`.loki`, `test_check.loki`), with the shared ones they load from the [`dev`](https://github.com/MadBomber/dev) repository (`quality.loki`, `gem_tasks.loki`, `git.loki`, `doc_tasks.loki`), are a real multi-file project: quality gates that return `:pass` or `:fail`, a background job, a subcommand group, a `helper` feeding the `header`, and deliberate overrides that `--doctor` reports. Copy what fits.
840
843
 
841
844
  - **More examples.** [MadBomber/dev](https://github.com/MadBomber/dev) holds shared `.loki` libraries used across many repos: gem, git, Rails quality, schedule, status report and iTerm tasks. The [examples directory](examples/) here has one small file per feature.
842
845
 
@@ -846,7 +849,7 @@ end
846
849
 
847
850
  - **Make bare `asgard` do the common thing.** `default_task :test` (or `:quality`, as this repo does) saves typing on the task you run most.
848
851
 
849
- - **Flags go after the task name.** `asgard build --verbose` runs the task; `asgard --verbose build` prints the help for `build`. Only `--version` and `--doctor` go first.
852
+ - **Flags go after the task name.** `asgard build --verbose` is the form to use. `--debug` and `--verbose` are also understood in front of a task name, so `asgard --verbose build` runs `build`; in front of any other word they run the `default_task` with that word as its argument. `--version` and `--doctor` go first.
850
853
 
851
854
  - **See the tasks by file with `asgard --doctor`.** It lists every `.loki` file that loaded and, under each, the tasks that file defines with their line numbers, plus which `.loki` won the walk up the tree, what every `import` loaded, tasks hidden because they lack a `desc`, and definitions silently replaced by a later one. It works even when the `.loki` will not load.
852
855
 
@@ -862,6 +865,8 @@ end
862
865
 
863
866
  - **An AI agent is just another shell.** Register a coding agent's CLI with `shell` and a heredoc becomes the prompt: [`examples/robots/.loki`](examples/robots/.loki) wires up `claude -p` in one line, and its `ask` task sends a prompt with a plain `sh :claude, <<~PROMPT`. Any agent that reads a prompt from stdin fits the same way, so a task can review a diff, draft release notes or explain a failing test alongside the tasks that run them.
864
867
 
868
+ - **A graph of steps inside one task.** `depends_on` orders whole tasks. When one task needs its own fan-out and fan-in, with output passed from step to step, run a [simple_flow](https://github.com/MadBomber/simple_flow) pipeline in the task body: [`examples/simple_flow/.loki`](examples/simple_flow/.loki) shows one. Run each step's command with `IO.popen` or `system` and halt the pipeline on failure; `sh` inside a step would exit asgard before the pipeline could report.
869
+
865
870
  - **Prefer `background: true` to a trailing `&`.** A managed job gets a name, a log and `asgard jobs stop`; a process detached with `&` leaves no record and must be found with `ps`.
866
871
 
867
872
  - **Import conditionally.** `.loki` is plain Ruby: `import "quality_rails.loki" if ENV["RAILS_ROOT"]` keeps Rails-only gates out of non-Rails projects, and a block-form `depends_on` picks up whatever `*_check` tasks are loaded.
@@ -876,6 +881,7 @@ More tips live in the manual at [Tips](https://madbomber.github.io/asgard/tips/)
876
881
 
877
882
  ```bash
878
883
  git clone git@github.com:MadBomber/asgard.git
884
+ git clone git@github.com:MadBomber/dev.git # shared task files, beside asgard
879
885
  cd asgard
880
886
  bundle install
881
887
  bundle exec bin/asgard test_check # run tests (95% coverage minimum enforced)
@@ -120,22 +120,30 @@ module Asgard
120
120
  end
121
121
 
122
122
  def _check_undefined_deps!(all_task_names)
123
- undefined = _deps.values.flatten.uniq - all_task_names
123
+ undefined = _dep_declarers.except(*all_task_names)
124
124
  return unless undefined.any?
125
125
 
126
- raise Asgard::Error, "undefined task(s) in depends_on: #{undefined.sort.join(', ')}"
126
+ details = undefined.sort.map do |dep, tasks|
127
+ "#{dep} (needed by #{tasks.sort.join(', ')})"
128
+ end
129
+ raise Asgard::Error, "undefined task(s) in depends_on: #{details.join(', ')}"
127
130
  end
128
131
 
129
132
  def _check_dep_arities!
130
- _deps.each_value do |stages|
131
- stages.flatten.each do |dep|
132
- meth = instance_method(dep.to_s)
133
- required = meth.parameters.count { |type, _| type == :req }
134
- next unless required.positive?
135
-
136
- raise Asgard::Error,
137
- "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency"
138
- end
133
+ _dep_declarers.sort.each do |dep, tasks|
134
+ required = instance_method(dep.to_s).parameters.count { |type, _| type == :req }
135
+ next unless required.positive?
136
+
137
+ raise Asgard::Error,
138
+ "task '#{dep}' has #{required} required argument(s) and cannot be used as a dependency " \
139
+ "(needed by #{tasks.sort.join(', ')})"
140
+ end
141
+ end
142
+
143
+ # Each dependency mapped to the tasks whose depends_on names it.
144
+ def _dep_declarers
145
+ _deps.each_with_object({}) do |(task, stages), declarers|
146
+ stages.flatten.uniq.each { |dep| (declarers[dep] ||= []) << task }
139
147
  end
140
148
  end
141
149
 
@@ -74,6 +74,13 @@ module Asgard
74
74
  Thor::Options.new(bare, {}, false, true).parse(raw).to_h
75
75
  end
76
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
+
77
84
  # A copy of +option+ that parses the same words but has no default.
78
85
  def self.without_default(option)
79
86
  Thor::Option.new(option.name, type: option.type, aliases: option.aliases, enum: option.enum,
@@ -125,7 +132,7 @@ module Asgard
125
132
 
126
133
  # Dispatch hook: resolves and runs all deps (in parallel where declared)
127
134
  # before executing the target command.
128
- def invoke_command(command, *)
135
+ def invoke_command(command, args = [])
129
136
  $DEBUG = true if options[:debug]
130
137
  $VERBOSE = true if options[:verbose]
131
138
  target = command.name.to_sym
@@ -139,8 +146,8 @@ module Asgard
139
146
  error = nil
140
147
  begin
141
148
  result = _in_task_frame(target) do
142
- resolved_deps = _run_deps_for(target)
143
- _with_dep_results(resolved_deps) { command.run(self, *) }
149
+ resolved_deps = _callable_with?(target, args) ? _run_deps_for(target) : {}
150
+ _with_dep_results(resolved_deps) { command.run(self, args) }
144
151
  end
145
152
  rescue Exception => e # rubocop:disable Lint/RescueException -- an exit or interrupt ends the task too
146
153
  # Captured here, not read from $! in an ensure: $! still holds a
@@ -231,6 +238,13 @@ module Asgard
231
238
  end
232
239
  end
233
240
 
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
+
234
248
  def _run_deps_for(target)
235
249
  stages = self.class._deps[target]
236
250
  return {} unless stages&.any?
@@ -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
@@ -59,6 +65,20 @@ module Asgard
59
65
  end
60
66
  super
61
67
  end
68
+
69
+ # Thor runs the default task when the command line is empty or starts
70
+ # with an option it does not map. A default_task that names no task
71
+ # would then fail as `Could not find command "".`, so name it.
72
+ def check_default_task!(argv)
73
+ first = argv.first
74
+ return if first && (map.key?(first) || !first.start_with?("-"))
75
+
76
+ name = default_command.to_s
77
+ return if all_commands.key?(name.tr("-", "_"))
78
+
79
+ where = " (set at #{@_default_task_location.path}:#{@_default_task_location.lineno})" if @_default_task_location
80
+ raise Asgard::Error, "default_task :#{name}#{where} is not a task"
81
+ end
62
82
  end
63
83
  end
64
84
  end
data/lib/asgard/base.rb CHANGED
@@ -109,6 +109,12 @@ module Asgard
109
109
  (Thor.private_method_defined?(method_name) && !Kernel.respond_to?(method_name))
110
110
  end
111
111
 
112
+ # Whether +word+, given to help as a command name, is an option Thor
113
+ # did not recognise. Thor's own help flags (-h, --help) are not.
114
+ def unknown_option?(word)
115
+ word.to_s.start_with?("-") && !Thor::HELP_MAPPINGS.include?(word)
116
+ end
117
+
112
118
  # The task `asgard help NAME` describes: a built-in group's mapped
113
119
  # name ("jobs") is its registered subcommand ("_jobs"); anything else
114
120
  # is NAME unchanged.
@@ -118,13 +124,20 @@ module Asgard
118
124
  end
119
125
 
120
126
  def _check_reserved_name!(method_name)
121
- thor = RESERVED_NAMES.include?(method_name)
122
- return unless thor || ASGARD_HELPERS.include?(method_name)
127
+ return unless _reserved_name?(method_name)
123
128
 
124
129
  file, line = instance_method(method_name).source_location
125
130
  remove_method(method_name) # leave the original in place, so the class still dispatches
126
- what = thor ? "a name Thor reserves" : "an asgard helper"
127
- raise Asgard::Error, "'#{method_name}' at #{file}:#{line} is #{what} and cannot be a task or helper; rename it"
131
+ _raise_reserved_name!(method_name, file, line)
132
+ end
133
+
134
+ # Whether +name+ is one a task or helper cannot take.
135
+ def _reserved_name?(name) = RESERVED_NAMES.include?(name) || ASGARD_HELPERS.include?(name)
136
+
137
+ # Raises the reserved-name error for +name+, defined at +file+:+line+.
138
+ def _raise_reserved_name!(name, file, line)
139
+ what = RESERVED_NAMES.include?(name) ? "a name Thor reserves" : "an asgard helper"
140
+ raise Asgard::Error, "'#{name}' at #{file}:#{line} is #{what} and cannot be a task or helper; rename it"
128
141
  end
129
142
 
130
143
  # `private def helper = ...` makes the method private only after
@@ -193,8 +206,12 @@ module Asgard
193
206
  end
194
207
  end
195
208
 
209
+ # Thor hands an unknown leading option (`asgard --nope`) to the default
210
+ # command, help, as a command name; name it as the option it is.
196
211
  def help(command = nil, subcommand = false) # rubocop:disable Style/OptionalBooleanParameter
197
212
  klass = self.class
213
+ raise Asgard::Error, "unknown option '#{command}'; see asgard help" if klass.unknown_option?(command)
214
+
198
215
  top_level = command.nil?
199
216
  header_text = klass.header
200
217
  footer_text = klass.footer
@@ -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?
@@ -65,7 +69,10 @@ module Asgard
65
69
  colorize(31, "#{errors} problem(s), #{warns} warning(s).")
66
70
  end
67
71
 
72
+ # Coloured only on a terminal with NO_COLOR unset, as the list tables are.
68
73
  def colorize(code, text)
74
+ return text unless $stdout.tty? && !ENV.key?("NO_COLOR")
75
+
69
76
  "\e[#{code}m#{text}\e[0m"
70
77
  end
71
78
  end
@@ -7,12 +7,13 @@ module Asgard
7
7
  # more than one recorded location (the each/each_gem class of bug) —
8
8
  # earlier ones OVERRIDDEN (dead), the last one the active redefinition.
9
9
  module TaskSections
10
- # A hidden task (one defined without a desc) says so, after any
11
- # override note.
12
- def self.with_hidden(status, hidden)
13
- return status unless hidden
10
+ # A hidden task says so, after any override note, and says why: no
11
+ # desc, or a desc given hide: true.
12
+ def self.with_hidden(status, command)
13
+ return status unless command.hidden?
14
14
 
15
- [status, "hidden (no desc; not shown by help)"].compact.join("; ")
15
+ reason = command.description == Base.singleton_class::HIDDEN_DESC ? "no desc" : "hide: true"
16
+ [status, "hidden (#{reason}; not shown by help)"].compact.join("; ")
16
17
  end
17
18
 
18
19
  private
@@ -33,7 +34,7 @@ module Asgard
33
34
  command = commands[name.to_s] or next
34
35
 
35
36
  locations.each_with_index do |(file, line), idx|
36
- file_map[file] << [name, line, TaskSections.with_hidden(task_status(locations, idx), command.hidden?)]
37
+ file_map[file] << [name, line, TaskSections.with_hidden(task_status(locations, idx), command)]
37
38
  end
38
39
  end
39
40
  file_map.each_value { |tasks| tasks.sort_by! { |t| t[1] } }
data/lib/asgard/doctor.rb CHANGED
@@ -29,23 +29,14 @@ module Asgard
29
29
  build_task_sections
30
30
  report_dependencies
31
31
  print_report
32
+ problem_count.zero? ? 0 : 1
32
33
  end
33
34
 
34
35
  # Every ".loki" marker from +dir+ up to the filesystem root, nearest
35
- # first — mirrors loki_up's walk, but collects every match instead of
36
+ # first — the same walk as loki_up, but collects every match instead of
36
37
  # stopping at the first (so shadowed ancestor markers can be reported).
37
38
  def self.ancestor_markers(dir)
38
- markers = []
39
- current = Pathname.new(dir)
40
- loop do
41
- candidate = current + ".loki"
42
- markers << candidate.to_s if candidate.file?
43
- parent = current.parent
44
- break if parent == current
45
-
46
- current = parent
47
- end
48
- markers
39
+ Pathname.new(dir).ascend.map { it + ".loki" }.select(&:file?).map(&:to_s)
49
40
  end
50
41
 
51
42
  # method_name => [[file, line], ...] entries defined more than once —
@@ -57,6 +48,23 @@ module Asgard
57
48
  end
58
49
  end
59
50
 
51
+ # The "load failed" line for whatever stopped the .loki chain loading.
52
+ # An exit or abort raises SystemExit; a bare exit (or raise SystemExit)
53
+ # carries only a default message, so only the status is worth showing then.
54
+ def self.load_failure(error)
55
+ return "load failed: #{error.class}: #{error.message}" unless error.is_a?(SystemExit)
56
+
57
+ detail = ": #{error.message}" unless ["exit", error.class.to_s].include?(error.message)
58
+ "load failed: #{error.class} (status #{error.status})#{detail}"
59
+ end
60
+
61
+ # What ImportTracer saw one import or import_up do: the line the report
62
+ # prints for it, and the .loki files it loaded.
63
+ def record_import(message, added = [])
64
+ @imports << message
65
+ @loaded_files.concat(added)
66
+ end
67
+
60
68
  private
61
69
 
62
70
  def report_markers
@@ -77,16 +85,16 @@ module Asgard
77
85
  return unless @marker
78
86
 
79
87
  Kernel.prepend(ImportTracer)
80
- ImportTracer.doctor = self
88
+ ImportTracer.observe(self)
81
89
  @loaded_files << @marker
82
90
 
83
91
  before = Asgard::Base._asgard_subclasses.dup
84
92
  Asgard.load_root(@marker)
85
93
  @new_subclasses = (Asgard::Base._asgard_subclasses - before + [Tasks]).uniq
86
- rescue StandardError, ScriptError => e
87
- @findings << Finding.new(level: :error, message: "load failed: #{e.class}: #{e.message}")
94
+ rescue StandardError, ScriptError, SystemExit => e
95
+ @findings << Finding.new(level: :error, message: self.class.load_failure(e))
88
96
  ensure
89
- ImportTracer.doctor = nil
97
+ ImportTracer.observe(nil)
90
98
  end
91
99
 
92
100
  def report_imports
@@ -103,18 +111,16 @@ module Asgard
103
111
  end
104
112
  end
105
113
 
106
- def record_import(message, added = [])
107
- @imports << message
108
- @loaded_files.concat(added)
109
- end
110
-
111
114
  # Prepended onto Kernel for the process lifetime of `asgard --doctor`
112
115
  # (Asgard.run! exits right after Doctor#run, so it's never unprepended)
113
116
  # to observe every import/import_up call, whether typed at the top
114
117
  # level of a .loki file or reached indirectly through another import.
115
118
  module ImportTracer
116
119
  class << self
117
- attr_accessor :doctor
120
+ # The Doctor that records each import, or nil when none is running.
121
+ attr_reader :doctor
122
+
123
+ def observe(doctor) = @doctor = doctor
118
124
  end
119
125
 
120
126
  def import(path)
@@ -122,7 +128,7 @@ module Asgard
122
128
  before = $LOADED_FEATURES.dup
123
129
  result = super(path, from: loc)
124
130
  added = ImportTracer.loki_files($LOADED_FEATURES - before)
125
- ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import", path, added), added) unless
131
+ ImportTracer.doctor&.record_import(ImportTracer.trace_message("import", path, added), added) unless
126
132
  loc&.absolute_path&.end_with?("kernel_methods.rb")
127
133
  result
128
134
  end
@@ -131,7 +137,7 @@ module Asgard
131
137
  before = $LOADED_FEATURES.dup
132
138
  result = super
133
139
  added = ImportTracer.loki_files($LOADED_FEATURES - before)
134
- ImportTracer.doctor&.send(:record_import, ImportTracer.trace_message("import_up", name, added), added)
140
+ ImportTracer.doctor&.record_import(ImportTracer.trace_message("import_up", name, added), added)
135
141
  result
136
142
  end
137
143