whatnext 2.0__tar.gz

whatnext-2.0/.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E131

whatnext-2.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

whatnext-2.0/.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install whatnext
+        run: pip install .[test]
+
+      - name: Install testing dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats ripgrep
+
+      - name: Run tests
+        run: make test
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    runs-on: ubuntu-latest
+    needs: publish
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Get version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract changelog for version
+        id: changelog
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          changelog=$(awk -v ver="$version" '
+            /^## \[/ {
+              if (found) exit
+              if ($0 ~ "\\[v" ver "\\]") found=1
+              next
+            }
+            found { print }
+          ' CHANGELOG.md)
+          {
+            echo "notes<<EOF"
+            echo "$changelog"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NOTES: ${{ steps.changelog.outputs.notes }}
+        run: |
+          version="${{ steps.version.outputs.version }}"
+          pypi_link="https://pypi.org/project/whatnext/${version}/"
+          full_notes=$(printf '%s\n\n---\n[pypi release](%s)' "$NOTES" "$pypi_link")
+          gh release create "${{ github.ref_name }}" \
+            --title "whatnext ${version}" \
+            --notes "$full_notes"

whatnext-2.0/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install whatnext
+        run: pip install .[test]
+
+      - name: Install testing dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats ripgrep
+
+      - name: Run tests
+        run: make test

whatnext-2.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/

whatnext-2.0/.whatnext

@@ -0,0 +1,7 @@
+# not considered in any summaries
+ignore = [
+    'README.md',
+    'example/*',
+    'tests/*',
+    'docs/*',
+]

whatnext-2.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+
+## [v2.0] - 2026-01-28
+
+**Breaking change:** `whatnext` now ignores tasks and headers within
+quoting elements -- blockquotes, code fences, and indented text.
+
+**Fixes:**
+- bug in relative summaries was reusing characters for different states
+
+
+## [v1.4] - 2026-01-27
+
+`next` now shows a diff of the change made to the task file.
+
+Prefer `tasks.md` in the current directory to `~/tasks.md`.
+
+**Fixes:**
+- Bare `@after` waiting for all incomplete tasks, including those with
+  `@after file.md` dependencies.
+- `next` rejecting task text containing flag-like arguments (e.g. `-e`).
+- `next -a` inserting after the last task instead of at the end of the file.
+
+
+## [v1.3.2] - 2026-01-11
+
+Fixed repeated warnings when a file has a missing `@after` dependency.
+
+Added `--ignore-after` flag to show all outstanding tasks regardless of
+`@after` constraints.
+
+
+## [v1.3.1] - 2026-01-10
+
+Fixed file-level `@after` being ignored when the file has no headings.
+
+
+## [v1.3] - 2026-01-09
+
+Added `next` command to quickly add tasks from the command line.
+
+Files can self-exclude from results using `@notnext`.
+
+
+## [v1.2] - 2026-01-08
+
+Files, sections, or individual tasks can be deferred using `@after` to hide
+them until other tasks are complete.
+
+Added `--guide` to show a short Markdown formatting reference, separating
+it out of the `--help` usage.
+
+
+## [v1.1] - 2025-12-04
+
+Fixed relative summaries to include all tasks, not just some.
+
+Removed slashes from summary columns for cleaner output.
+
+Added `-e`/`--edit` flag to open task files in your editor at the line number
+of the first matching task.
+
+
+## [v1.0] - 2025-12-02
+
+Output is now colour-coded by default, override with `--color/--no-color`
+or by setting `WHATNEXT_COLOR`.
+
+Focused task selection:
+
+- `whatnext 5` will show the five highest status tasks.
+- `whatnext 5r` will show five randomly selected tasks.
+
+Annotations, including a ` ```whatnext ` fenced block allows notes that appear
+in context in the output.
+
+Include totals in summaries.
+
+
+## [v0.5] - 2025-12-01
+
+Tasks can have deadlines using the `@YYYY-MM-DD/4w` syntax. As the deadline
+approaches, the task's priority automatically shifts to `imminent` (two weeks
+before by default). Once past the deadline, the priority becomes `overdue`.
+
+
+## [v0.4] - 2025-12-01
+
+Individual tasks and sections of tasks can be marked with emphasis to denote
+\_medium\_ priority or as \*\*high\*\* priority. They will be displayed at the
+top of the output, each priority in separate blocks.
+
+
+## [v0.3] — 2025-11-29
+
+Adding more states to the roster, tasks can be marked as open (unstarted),
+in progress, cancelled, blocked, and completed.
+
+Tasks can be filtered by any of these states when showing tasks or summaries.
+
+
+## [v0.2] — 2025-11-28
+
+Filtering tasks by text/header can be helpful. And as useful as it
+can be to use `--dir` to specify the base dir, sometimes you just
+want to do it quicker, so you can also specify a dir or file as
+an argument to restrict searching just to that.
+
+Arguments can be mixed and matched freely. Multiple search terms
+are additive not exclusive.
+
+
+## [v0.1] — 2025-11-28
+
+First version, very basic. Lists tasks found in Markdown files in a
+given directory. Can produce summaries.

whatnext-2.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mark Norman Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

whatnext-2.0/LICENSE

@@ -0,0 +1 @@
+LICENCE

whatnext-2.0/Makefile

@@ -0,0 +1,18 @@
+ifndef CI
+ifndef VIRTUAL_ENV
+$(error Development has to happen inside venv, whatnext is also installed globally.)
+endif
+endif
+
+.PHONY: test flake8 pytest bats
+
+test: flake8 pytest bats
+
+flake8:
+	flake8 whatnext tests
+
+pytest: flake8
+	pytest tests/
+
+bats:
+	bats tests/*.bats

whatnext-2.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: whatnext
+Version: 2.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
+Project-URL: Documentation, https://github.com/norm/whatnext
+Author: Mark Norman Francis
+License-Expression: MIT
+License-File: LICENCE
+License-File: LICENSE
+Keywords: cli,markdown,tasks,todo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: termcolor
+Requires-Dist: toml
+Provides-Extra: test
+Requires-Dist: flake8; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# What next?
+
+I like to keep tasks in Markdown files. That way they can be interspersed
+within instructions, serving as reminders, FIXMEs, and other todos.
+
+All the features for enhancing your task lists are discussed in detail in
+[the documentation](https://github.com/norm/whatnext/blob/main/docs/index.md).
+
+Document your tasks using an expanded version of the original
+[GitHub task list notation][sn]:
+
+```markdown
+- [ ] open, this task is outstanding
+- [/] in progress, this task is partially complete
+- [X] complete, this task has been finished
+- [#] cancelled, this task has been scratched
+- [<] blocked, this task needs more input
+
+- [ ] _an important task_
+
+# **Make apple pie from scratch**
+- [ ] invent the universe
+
+# Things for later
+
+- [ ] get NYE fireworks tickets @2025-12-31
+- [ ] but in the end it doesn't even matter @after
+```
+
+Then install `whatnext`:
+
+```bash
+pip install whatnext
+```
+
+Now run it and it'll tell you what's next, sorting by priority and state:
+
+```bash
+(computer)% whatnext
+README.md:
+    # What next? / HIGH
+    - [ ] a lot more important
+
+README.md:
+    # What next? / MEDIUM
+    - [ ] a little more important
+
+README.md:
+    # What next? / IMMINENT 6d
+    - [ ] get NYE fireworks tickets
+
+README.md:
+    # What next?
+    - [/] in progress, this task is partially complete
+    - [ ] open, this task is outstanding
+    - [<] blocked, this task needs more input
+```
+
+Also provided, `next` to add tasks to files.
+
+```bash
+# by default, adds to $HOME/tasks.md
+(computer)% next Add more features to whatnext
+Updated tasks.md
+```
+
+[sn]: https://blog.github.com/2013-01-09-task-lists-in-gfm-issues-pulls-comments/

whatnext-2.0/README.md

@@ -0,0 +1,67 @@
+# What next?
+
+I like to keep tasks in Markdown files. That way they can be interspersed
+within instructions, serving as reminders, FIXMEs, and other todos.
+
+All the features for enhancing your task lists are discussed in detail in
+[the documentation](docs/index.md).
+
+Document your tasks using an expanded version of the original
+[GitHub task list notation][sn]:
+
+```markdown
+- [ ] open, this task is outstanding
+- [/] in progress, this task is partially complete
+- [X] complete, this task has been finished
+- [#] cancelled, this task has been scratched
+- [<] blocked, this task needs more input
+
+- [ ] _an important task_
+
+# **Make apple pie from scratch**
+- [ ] invent the universe
+
+# Things for later
+
+- [ ] get NYE fireworks tickets @2025-12-31
+- [ ] but in the end it doesn't even matter @after
+```
+
+Then install `whatnext`:
+
+```bash
+pip install whatnext
+```
+
+Now run it and it'll tell you what's next, sorting by priority and state:
+
+```bash
+(computer)% whatnext
+README.md:
+    # What next? / HIGH
+    - [ ] a lot more important
+
+README.md:
+    # What next? / MEDIUM
+    - [ ] a little more important
+
+README.md:
+    # What next? / IMMINENT 6d
+    - [ ] get NYE fireworks tickets
+
+README.md:
+    # What next?
+    - [/] in progress, this task is partially complete
+    - [ ] open, this task is outstanding
+    - [<] blocked, this task needs more input
+```
+
+Also provided, `next` to add tasks to files.
+
+```bash
+# by default, adds to $HOME/tasks.md
+(computer)% next Add more features to whatnext
+Updated tasks.md
+```
+
+[sn]: https://blog.github.com/2013-01-09-task-lists-in-gfm-issues-pulls-comments/

whatnext-2.0/archive/done/tasks.md

@@ -0,0 +1,5 @@
+# Some old stuff
+
+- [X] Do the first thing
+- [X] Do the second thing
+- [x] do the last thing all lowercase

whatnext-2.0/docs/annotations.md

@@ -0,0 +1,17 @@
+# Annotations
+
+If you need any explanatory text to appear in the output along with the
+task(s), add a named fence block to the file:
+
+````markdown
+# Project Anvil
+
+```whatnext
+Let the anvils ring!
+```
+
+- [ ] introduce ourselves
+- [ ] inherit throne
+````
+
+Other named and unnamed fence blocks are ignored.

whatnext-2.0/docs/basics.md

@@ -0,0 +1,48 @@
+# Indicating the state of a task
+
+Tasks have states, which are indicated as such:
+
+```markdown
+- [ ] open, this task is outstanding
+- [/] in progress, this task is partially complete
+- [X] complete, this task has been finished
+- [#] cancelled, this task has been scratched
+- [<] blocked, this task needs more input
+
+- [@] no idea what this means
+```
+
+By default, `whatnext` lists open, in progress, and blocked tasks. In progress
+tasks are shown first, blocked tasks are shown last. Completed and cancelled
+tasks are not listed unless `--all` is used.
+
+Headers are used in grouping tasks. The second-level header that comes next
+shows these tasks are a part of the main header. This does not indicate
+a lower priority, only grouping.
+
+An unknown state marker will generate a warning, but they can be suppressed
+if you are using other states for a purpose.
+
+
+## Multiline tasks and indentation
+
+Tasks can be indented, and their text can continue across lines:
+
+```markdown
+    - [ ] Lorem ipsum dolor sit amet,
+          consectetur adipisicing elit,
+          sed do  eiusmod  tempor   incididunt
+          ut labore et     dolore magna aliqua.
+```
+
+The output of `whatnext` will wrap text to the terminal width, and does not
+consider spacing of individual words or line wrapping semantically important.
+
+Indentation of individual tasks is ignored, but the continuation has
+to be indented to match, unlike in this task which is detected as
+"Ut enim ad minim veniam," only:
+
+```markdown
+    - [ ] Ut enim ad minim veniam,
+         quis nostrud exercitation ullamco laboris
+```

whatnext-2.0/docs/deadlines.md

@@ -0,0 +1,44 @@
+# Deadlines
+
+Tasks can be marked as needing to be done by a certain date:
+
+```markdown
+# version 0.5
+- [ ] complete and release @2025-12-05
+```
+
+This task has not been given a priority, so would appear in the bulk of the
+task list. That is, until two weeks before the date mentioned, at which point
+it will be given a priority of `imminent`. And if the date is now in the past,
+the priority set will be `overdue`.
+
+The default two-week urgency window in which a task is marked imminent
+can be controlled:
+
+```markdown
+# Christmas dinner
+- [ ] book Christmas delivery @2025-12-23/3w
+```
+
+The `/1d` adjustment can be a number of days or weeks. `/0d` means the
+task will only change priority on the day itself.
+
+If you need to include it without it being parsed, either surround it in
+backticks (` `@YYYY-...` `) or put a backslash before (`\@YYYY-...`).
+
+
+# Deadlines and priorities
+
+Due date takes precedence over priorities. Assuming the date today was
+December 1st, both of these tasks would be listed as having normal
+priority.
+
+```
+# Christmas dinner
+- [ ] _prep the make-ahead gravy_ @2025-12-25/1d
+- [ ] **roast the potatoes** @2025-12-25/0d
+- [ ] prep sprouts @2025-12-25
+```
+
+Later, gravy would appear as medium priority on December 24th,
+and potatoes as high priority on December 25th.

whatnext-2.0/docs/deferring.md

@@ -0,0 +1,42 @@
+# Deferring tasks
+
+Some tasks either can't or won't be considered until some other tasks
+are done, so you can indicate that these tasks _should not show up_ yet:
+
+    # Someday
+
+    @after
+
+    - [ ] rewrite everything in Rust
+
+`@after` on a line by itself applies to the whole file, on a header it
+applies to the section, and on a task only applies to that task.
+
+If you need to include it without it being parsed, either surround it in
+backticks (` `@after` `) or put a backslash before (`\@after`).
+
+To ignore this when querying for tasks, use `whatnext --ignore-after`
+(plus `whatnext --all` will always show all tasks regardless).
+
+
+## After ... what?
+
+Without any clarification, any deferred tasks will only appear in `whatnext`
+output once every other non-deferred task is completed.
+
+If you are trying to define project dependencies, you can indicate this
+by naming the other task file(s):
+
+    # Stage three
+
+    @after stage_one.md stage_two.md
+
+    - [ ] design the booster separation
+
+Filenames are compared against all task files found, without considering
+the directory they are in.
+
+Circular dependencies (where A depends on B and B depends on A) will
+cause an error showing the cycle. Referencing a nonexistent file will
+produce a warning.
+

whatnext-2.0/docs/exclusions.md

@@ -0,0 +1,36 @@
+# Excluding files
+
+If you need to ignore a file (or three), but don't want to keep typing out
+the `--ignore` option, there are two ways of doing this.
+
+## Exclude a single file
+
+To have a file declare itself not suitable for finding tasks within,
+add this marker anywhere in the file:
+
+```markdown
+@notnext [explanation if necessary]
+```
+
+## Exclude multiple files
+
+You can include a `.whatnext` file in the directory being examined for tasks:
+
+```toml
+# not considered in any summaries
+ignore = [
+    'README.md',
+    'tasks.md',
+    'docs/usage.md',
+]
+```
+
+If you need to store it somewhere else, or have it be a different
+filename, you can use the `--config` option, or set the location
+in the environment variable `WHATNEXT_CONFIG`.
+
+## Overriding exclusions
+
+Explicitly naming a file on the command line will show its tasks
+regardless of `@notnext` or ignore patterns. This allows you to
+query a specific file when needed without removing the exclusion.