whatnext 2.1__tar.gz → 3.0__tar.gz

{whatnext-2.1 → whatnext-3.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
 
+## [v3.0] - 2026-02-14
+
+**Breaking change:** `@after` filenames are now resolved relative to the
+file containing the directive, supporting
+
+```
+@after ../project-b/setup.md
+@after subtask/notes.md
+@after ~/tasks/dependency.md
+```
+
+Previously `whatnext` assumed a flat hierarchy of unique filenames.
+
+**Added:**
+- `@phase` directive in section headers creates a dependency chain within
+  the file; the first phase is always visible, and subsequent phases
+  will only show when all previous phases are complete.
+
+**Fixes:**
+- `@after` referencing a file excluded by `--ignore` no longer warns about
+  the file not existing, instead treating the dependency as complete.
+
+
 ## [v2.0] - 2026-02-09
 
 Added `@queue` directive show only one task at a time, for simple sequential

{whatnext-2.1 → whatnext-3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: whatnext
-Version: 2.1
+Version: 3.0
 Summary: A lister of tasks found in Markdown files
 Project-URL: Homepage, https://github.com/norm/whatnext
 Project-URL: Repository, https://github.com/norm/whatnext

{whatnext-2.1 → whatnext-3.0}/docs/deferring.md

@@ -33,8 +33,12 @@ by naming the other task file(s):
 
     - [ ] design the booster separation
 
-Filenames are compared against all task files found, without considering
-the directory they are in.
+Filenames are resolved relative to the file containing the `@after`
+directive.
+
+    @after ../project-b/setup.md
+    @after subtask/notes.md
+    @after ~/tasks/dependency.md
 
 Circular dependencies (where A depends on B and B depends on A) will
 cause an error showing the cycle. Referencing a nonexistent file will

{whatnext-2.1 → whatnext-3.0}/docs/index.md

@@ -56,8 +56,8 @@ and sections can have [annotations included](annotations.md).
 If a task has a dependency on other tasks, such that it cannot be done in any
 order, you can [defer tasks](deferring.md) until all/some other tasks are complete.
 
-For sequential work where only one task can be done at a time, you can
-[limit output](sequential.md) to the next open task in the file.
+For sequential work where only one task or small group of tasks can be done at
+a time, you can [limit output](sequential.md) within the file.
 
 If you need to exclude out some Markdown files for any reason, there are
 [two ways to do that](exclusions.md).

{whatnext-2.1 → whatnext-3.0}/docs/sequential.md

@@ -1,5 +1,10 @@
 # Sequential tasks
 
+For ordering tasks within a file, you can use `@queue` and `@phase`.
+
+
+## One task at a time
+
 For simpler work that is done sequentially, either because they have to be
 done one-after-the-other, or because they represent larger blocks that are
 not broken down into subtasks, add `@queue` to the file:
@@ -24,3 +29,28 @@ auditing.md:
 ```
 
 When querying with `--all` or `--summary` arguments, all tasks are presented.
+
+
+## One section at a time
+
+For work with multiple tasks with an inherent grouping and you don't want to
+break the work into multiple files, instead break the work into sections and
+include `@phase` in the header:
+
+```markdown
+# Red @phase
+- [ ] add/amend tests to assert desired behaviour
+- [ ] prove new tests fail
+
+# Green @phase
+- [ ] update code to implement desired behaviour
+- [ ] prove tests pass
+
+# Refactor @phase
+- [ ] simplify and improve new code
+- [ ] prove tests still pass
+```
+
+This creates a dependency chain within the file; the first phase is
+always visible, and subsequent phases will only show when all previous
+phases are complete.

{whatnext-2.1 → whatnext-3.0}/example/projects/curtain.md

@@ -2,7 +2,7 @@
 
 @after
 
-## Final bow @after tangerine.md
+## Final bow @after ../archived/projects/tangerine.md
 
 - [ ] Take a bow
 

whatnext-3.0/tasks/deferring.md

@@ -0,0 +1,24 @@
+Deferring tasks improvements.
+
+- [X] what if an \@after file is queried solo on the command line?
+- [#] \@after with headers from the current file, not just filenames?
+      (decided on \@phase, below)
+- [X] \@after combined with --ignore on the command line produces warnings,
+      it should check we're not deliberately ignoring
+
+Deferring to another file should be relative to the current file, but it
+is not working:
+
+```
+(computer)% whatnext
+WARNING: tasks/notebooks.md: 'wiki/modelling.md' does not exist
+```
+
+- [X] \@after should be relative to the file in question
+- [X] \@after filenames should support `~/...` as a shortcut to `$HOME`
+
+`@phase` in a section header creates a dependency chain within the file.
+Later sections also tagged with phase are not shown when earlier phases
+are incomplete. Non-tagged sections are shown as normal.
+
+- [X] implement \@phase directive for section-level sequencing

whatnext-3.0/tests/deferring/needs-absolute.md

@@ -0,0 +1 @@
+- [ ] depends on absolute path @after /tmp/whatnext-test-prereq.md

whatnext-3.0/tests/deferring/needs-subdir.md

@@ -0,0 +1 @@
+- [ ] depends on subdir file @after subdir/target.md

whatnext-3.0/tests/deferring/phase-misplaced.md

@@ -0,0 +1,3 @@
+@phase
+
+- [ ] task with misplaced phase directive

whatnext-3.0/tests/deferring/phases-empty.md

@@ -0,0 +1,10 @@
+# Setup @phase
+
+- [X] install dependencies
+
+# Configuration @phase
+
+# Implementation @phase
+
+- [ ] write code
+- [ ] add tests

whatnext-3.0/tests/deferring/phases-partial.md

@@ -0,0 +1,15 @@
+# Bugs
+
+- [ ] fix bug
+
+# Setup @phase
+
+- [X] install dependencies
+
+# Implementation @phase
+
+- [ ] write code
+
+# Testing @phase
+
+- [ ] run tests

whatnext-3.0/tests/deferring/phases-queue.md

@@ -0,0 +1,16 @@
+@queue
+
+# Setup @phase
+
+- [X] first setup task
+- [X] second setup task
+
+# Implementation @phase
+
+- [ ] first impl task
+- [ ] second impl task
+
+# Refactor @phase
+
+- [ ] make it easier to read
+- [ ] make it faster

whatnext-3.0/tests/deferring/phases.md

@@ -0,0 +1,15 @@
+# Bugs
+
+- [ ] fix bug
+
+# New feature @phase
+
+- [ ] install dependencies
+
+## Implement @phase
+
+- [ ] write code
+
+## Test @phase
+
+- [ ] run tests

whatnext-3.0/tests/deferring/root-target.md

@@ -0,0 +1 @@
+- [X] complete target at root

whatnext-3.0/tests/deferring/samename.md

@@ -0,0 +1 @@
+- [ ] incomplete task at root

whatnext-3.0/tests/deferring/subdir/needs-parent.md

@@ -0,0 +1 @@
+- [ ] depends on parent file @after ../root-target.md

whatnext-3.0/tests/deferring/subdir/needs-sibling.md

@@ -0,0 +1 @@
+- [ ] depends on sibling @after samename.md

whatnext-3.0/tests/deferring/subdir/samename.md

@@ -0,0 +1 @@
+- [X] complete task in subdir

whatnext-3.0/tests/deferring/subdir/target.md

@@ -0,0 +1 @@
+- [X] complete target in subdir

whatnext-3.0/tests/deferring.bats

@@ -0,0 +1,307 @@
+bats_require_minimum_version 1.5.0
+
+setup_file() {
+    echo "- [ ] complete task" > /tmp/whatnext-test-prereq.md
+}
+
+teardown_file() {
+    rm -f /tmp/whatnext-test-prereq.md
+}
+
+@test "circular dependency exits with error" {
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/circular-a.md \
+            tests/deferring/circular-b.md
+
+    expected_stderr=$(sed -e 's/^        //' <<"        EOF"
+        ERROR: Circular dependency: circular-a.md -> circular-b.md -> circular-a.md
+        EOF
+    )
+    diff -u <(echo "$expected_stderr") <(echo "$stderr")
+    [ $status -eq 1 ]
+}
+
+@test "warning on nonexistent file dependency" {
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/missing-dep.md
+
+    expected_stderr=$(sed -e 's/^        //' <<"        EOF"
+        WARNING: tests/deferring/missing-dep.md: 'nonexistent.md' does not exist
+        EOF
+    )
+    diff -u <(echo "$expected_stderr") <(echo "$stderr")
+    [ $status -eq 0 ]
+}
+
+@test "all errors and warnings shown" {
+    run --separate-stderr \
+        whatnext \
+            tests/deferring
+
+    expected_stderr=$(sed -e 's/^        //' <<"        EOF"
+        WARNING: @phase has no meaning except in a header
+        WARNING: duplicate-warnings.md: 'missing-a.md' does not exist
+        WARNING: duplicate-warnings.md: 'missing-b.md' does not exist
+        WARNING: missing-dep.md: 'nonexistent.md' does not exist
+        ERROR: Circular dependency: circular-a.md -> circular-b.md -> circular-a.md
+        EOF
+    )
+    diff -u <(echo "$expected_stderr") <(echo "$stderr")
+    [ $status -eq 1 ]
+}
+
+@test "warnings are not duplicated" {
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/duplicate-warnings.md
+
+    expected_stderr=$(sed -e 's/^        //' <<"        EOF"
+        WARNING: tests/deferring/duplicate-warnings.md: 'missing-a.md' does not exist
+        WARNING: tests/deferring/duplicate-warnings.md: 'missing-b.md' does not exist
+        EOF
+    )
+    diff -u <(echo "$expected_stderr") <(echo "$stderr")
+    [ $status -eq 0 ]
+}
+
+@test "warning suppresseds" {
+    run --separate-stderr \
+        whatnext \
+            --quiet \
+            tests/deferring/missing-dep.md
+
+    diff -u <(echo "") <(echo "$stderr")
+    [ $status -eq 0 ]
+}
+
+@test "deferred tasks hidden by default" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/regular.md:
+            - [ ] do the thing
+        EOF
+    )
+
+    run whatnext tests/deferring/regular.md tests/deferring/deferred.md
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "tasks shown when file queried directly" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/bare-after.md:
+            - [ ] do this last
+        EOF
+    )
+
+    # nothing else is outstanding (as nothing else was loaded),
+    # so the contents should be shown
+    run whatnext tests/deferring/bare-after.md
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "after can be ignored" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/deferred.md:
+            - [ ] wait for regular
+        tests/deferring/regular.md:
+            - [ ] do the thing
+        EOF
+    )
+
+    run whatnext --ignore-after tests/deferring/regular.md tests/deferring/deferred.md
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "dependency treated as satisfied when file is deliberately ignored" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/deferred.md:
+            - [ ] wait for regular
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            --ignore regular.md \
+            tests/deferring/deferred.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    diff -u <(echo "") <(echo "$stderr")
+    [ $status -eq 0 ]
+}
+
+@test "after resolves bare filename relative to file" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/samename.md:
+            - [ ] incomplete task at root
+        tests/deferring/subdir/needs-sibling.md:
+            - [ ] depends on sibling
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/subdir/needs-sibling.md \
+            tests/deferring/subdir/samename.md \
+            tests/deferring/samename.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "after resolves path descending into subdirectory" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/needs-subdir.md:
+            - [ ] depends on subdir file
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/needs-subdir.md \
+            tests/deferring/subdir/target.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "after resolves path ascending to parent directory" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/subdir/needs-parent.md:
+            - [ ] depends on parent file
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/subdir/needs-parent.md \
+            tests/deferring/root-target.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "after resolves absolute path" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        /tmp/whatnext-test-prereq.md:
+            - [ ] complete task
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/needs-absolute.md \
+            /tmp/whatnext-test-prereq.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "phase sections filter later phases" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/phases.md:
+            # Bugs
+            - [ ] fix bug
+            # New feature [phase 1/3]
+            - [ ] install dependencies
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/phases.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "phase shows next when previous complete" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/phases-partial.md:
+            # Bugs
+            - [ ] fix bug
+            # Implementation [phase 2/3]
+            - [ ] write code
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/phases-partial.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "all phases shown with --all" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/phases.md:
+            # Bugs
+            - [ ] fix bug
+            # New feature [phase 1/3]
+            - [ ] install dependencies
+            # New feature / Implement [phase 2/3]
+            - [ ] write code
+            # New feature / Test [phase 3/3]
+            - [ ] run tests
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            --all \
+            tests/deferring/phases.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "queue limits tasks within phase" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/phases-queue.md:
+            # Implementation [phase 2/3]
+            - [ ] first impl task
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/phases-queue.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "empty phase skips to next" {
+    expected_output=$(sed -e 's/^        //' <<"        EOF"
+        tests/deferring/phases-empty.md:
+            # Implementation [phase 3/3]
+            - [ ] write code
+            - [ ] add tests
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/phases-empty.md
+
+    diff -u <(echo "$expected_output") <(echo "$output")
+    [ $status -eq 0 ]
+}
+
+@test "warning when @phase outside header" {
+    expected_stderr=$(sed -e 's/^        //' <<"        EOF"
+        WARNING: @phase has no meaning except in a header
+        EOF
+    )
+
+    run --separate-stderr \
+        whatnext \
+            tests/deferring/phase-misplaced.md
+
+    diff -u <(echo "$expected_stderr") <(echo "$stderr")
+    [ $status -eq 0 ]
+}