asgard 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c25b1efcac0de2f525140327f64753c1cb7b0cf82904ea6c4e1be1114b619bf
-  data.tar.gz: 857e98381996d06968944ed6bafb6b35d86073523672ac6d987ce2fb85a8cc79
+  metadata.gz: 2d904144543326c15257e4e61584c46fa9b0ab4f1ba522680daa930950361e6a
+  data.tar.gz: fea08260a5db1fdde268eaf4ca930b1e52a07a39f12eaf2ce20e31736319cdff
 SHA512:
-  metadata.gz: 383ececde0765e801b1e84dc239895ee0d2ffe491fc6d0c0c4d3a583f0a0912f64ca8dc4a4a6469f12efcae93358302ada9aeb648b6a95ada4fe866c205306b0
-  data.tar.gz: 3d2ecd3d0dcc3acdaa1ecd6dd6457ce02c23b086c36f178b9aa378ec620069ae99e9ecae3d824d26f0d22fb5906a4b34bc1831a2040abf24bab81833080b470e
+  metadata.gz: 9f75f50ba53970998d047e21078b120090ba6c232ac698b0ba705b84a3de542bfef313690e11d2e09989101045323c7cd6549bf51826b316ccf1beeb96ada50d
+  data.tar.gz: 497bee99076f476b8fe680962f59b369898381470b27fd59e0f7e4dc7636e620004660cbcf3ceb10a2678e65ddf78a2a7e24e6571362fc7ad3e7929eeb61a614

data/.loki

@@ -1,6 +1,8 @@
-# default task filename for the asgard task runner
+# frozen_string_literal: true
+# Asgard gem's own task file.
+# Task is pre-defined by the gem — just reopen it to add tasks.
 
-class Tasks < Asgard::Base
+class Tasks
   var :gem_name, "asgard"
   var :version,  -> { Asgard::VERSION }
 

data/CHANGELOG.md

@@ -7,13 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-28
+### Added
+
+- Parallel dependency execution — wrap deps in an array to run them concurrently:
+  `depends_on [:build, :lint]` or `depends_on :setup, [:build, :lint], :deploy`
+- `Asgard.run!(argv)` — single entry point encapsulating find, load, validate, and start
+- `Asgard.load_loki(dir)` — auto-loads all `*.loki` files in a directory alphabetically
+- `Tasks` class pre-defined by the gem (`class Tasks < Asgard::Base`) — task files reopen it without restating the superclass
+- `lib/asgard/tasks.rb` — ships the pre-defined `Tasks` class
+
+### Changed
+
+- Replaced `SimpleFlow` dependency with `Dagwood` — purpose-built DAG library with no extra dependencies and no Ruby 4 compatibility issues
+- `bin/asgard` simplified to two lines: `require "asgard"` + `Asgard.run!(ARGV)`
+- Task file convention: `.loki` is the project root marker and entry point; `*.loki` files each reopen `class Tasks` and are auto-loaded before `.loki`
+- `Asgard.find_task_files` renamed to `Asgard.find_task_file` (singular — only `.loki` is the entry point)
+- `depends_on` now accepts mixed sequential/parallel stages; bare symbols run sequentially, arrays within the splat run in parallel
+- `run!` handles its own errors — missing `.loki` and circular dependencies produce a clean one-line message and exit 1 rather than a backtrace
+- Thread-safe dep deduplication via class-level `_ran_tasks` Set + Mutex replaces Thor's `@_invocations`
+- Removed `import` macro — task files use Ruby class reopening instead of modules
+
+### Removed
+
+- `SimpleFlow` dependency (replaced by `Dagwood`)
+- `logger` gem workaround (was only needed for SimpleFlow on Ruby 4)
+- `*.loki` glob fallback in `find_task_file` — only `.loki` is the auto-discovered entry point
+
 ## [0.1.0] - 2026-05-28
 
 ### Added
 
 - `Asgard::Base` — Thor subclass providing the task DSL
-- `depends_on` — declare recipe dependencies resolved via `SimpleFlow::DependencyGraph`; dependencies run at most once per invocation
-- `var` — declare static or lazy-evaluated variables available to all recipes
+- `depends_on` — declare task dependencies; dependencies run at most once per invocation
+- `var` — declare static or lazy-evaluated variables available to all tasks
 - `import` — flat-merge a task module into the current class
 - `dotenv` — load a `.env` file into the environment
 - `sh` — run a shell command or multiline heredoc script; exits with the command's status on failure

data/CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What Asgard Is
+
+Asgard is a Ruby task runner. Users define tasks in `.loki` files by reopening the pre-defined `Tasks` class. The name is intentional: Thor handles the CLI, Asgard is where tasks live, and Loki (the `.loki` file) holds all the tricks.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test          # run tests (enforces 95% SimpleCov coverage)
+bundle exec rake quality       # test + flog complexity check
+bundle exec rake build         # build .gem into pkg/
+bundle exec rake install       # install locally
+
+# or use the gem's own .loki file:
+asgard test
+asgard quality
+asgard release
+```
+
+Single test: `ruby -Ilib:test test/test_asgard.rb`
+
+## Architecture
+
+### Entry Point Flow
+
+`bin/asgard` → `Asgard.run!(ARGV)` (`lib/asgard.rb`):
+1. Walk CWD + ancestors for `.loki` (marker only, not a task file)
+2. Glob + sort `*.loki` files from that dir, `load` each alphabetically
+3. Load `.loki` itself last
+4. `Tasks.validate_deps!` — build full dep graph, raise `CircularDependencyError` if cyclic
+5. `Tasks._reset_ran!` — clear execution tracking
+6. `Tasks.start(argv)` — Thor dispatches the command
+
+### Core Classes
+
+| File | Role |
+|------|------|
+| `lib/asgard/base.rb` | DSL engine; inherits Thor, includes Shell |
+| `lib/asgard/shell.rb` | `sh` / `shebang` helpers |
+| `lib/asgard/tasks.rb` | `class Tasks < Asgard::Base` — the convention class users reopen; also holds gem-owned built-in tasks |
+
+### Naming Convention for Gem-Owned Methods
+
+Any task or method defined by Asgard itself inside `Tasks` (i.e. not by the user's `.loki` files) must be prefixed with `_`. This distinguishes built-in gem behavior from user-defined tasks and prevents naming collisions.
+
+```ruby
+# lib/asgard/tasks.rb — gem-owned built-ins use _ prefix
+class Tasks < Asgard::Base
+  desc "--version", "Show version"
+  map "--version" => :_version
+  def _version
+    puts Asgard::VERSION
+    exit
+  end
+end
+```
+
+`method_added` in `Base` already skips `_`-prefixed methods when attaching dependency metadata, so built-ins are naturally excluded from the dependency graph.
+
+Do not define `_`-prefixed methods in user `.loki` files — that namespace is reserved for the gem.
+
+### DSL Mechanics (`lib/asgard/base.rb`)
+
+**`depends_on`** stores stages in `@_pending_deps`. On `method_added`, those stages are popped and stored in `@_deps[method_name]`. Bare symbols are sequential stages; arrays within a `depends_on` call are parallel stages:
+
+```ruby
+depends_on :a, [:b, :c], :d   # stages: [[:a], [:b, :c], [:d]]
+```
+
+**`var`** stores values or lambdas in `@_vars` and creates an instance method that evaluates the lambda once on first access.
+
+**`invoke_command`** (Thor dispatch hook):
+1. Atomically check `@_ran_tasks` Set (with `@_ran_mutex`); return early if already run
+2. Resolve `@_deps` stages → `_build_dep_graph` → `Dagwood::DependencyGraph#parallel_order`
+3. For each parallel group: spawn one thread per task, join; single-task groups run inline
+4. Execute the target task
+
+**`_build_dep_graph(stages)`** converts stages to a DAG hash:
+- `[[:a], [:b, :c], [:d]]` → `{ a: [], b: [:a], c: [:a], d: [:b, :c] }`
+
+### Dependency Resolution
+
+Dagwood topologically sorts the DAG and returns parallel groups. The thread-safe deduplication (`_ran_tasks` Set + Mutex) ensures each task runs exactly once even when multiple tasks share a common dependency.
+
+### Shell Helpers
+
+- `sh(script, silent: false)` — single-line strings use `system(script)`; multi-line strings pipe through `bash -c`; exits with the command's status on failure
+- `shebang(interpreter, script)` — writes script to a tempfile and executes with the named interpreter (`:python3`, `:node`, `:ruby`, `:perl`, `:bash`, etc.)
+
+## Testing
+
+All tests are in `test/test_asgard.rb` (one file, ~11 named classes). SimpleCov minimum is 95%; the Rakefile configures this with a prelude that loads coverage before the library.
+
+Key test patterns: tests frequently subclass `Asgard::Base` directly (not `Tasks`) to test the engine in isolation, and use `capture_io` for output assertions.
+
+## The `.loki` Format
+
+A `.loki` file is plain Ruby that reopens `Tasks`:
+
+```ruby
+class Tasks
+  var :gem_name, "asgard"
+
+  desc "test", "Run tests"
+  def test = sh "bundle exec rake test"
+
+  depends_on :test
+  desc "release", "Build and release"
+  def release = sh "bundle exec rake release"
+end
+```
+
+Multiple `*.loki` files in the same directory are all loaded (alphabetically). The bare `.loki` file serves only as the project root marker — its content is loaded last.