checkmarks 0.1.0__tar.gz → 0.2.0__tar.gz

checkmarks-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: checkmarks
+Version: 0.2.0
+Summary: Progress dashboard for Markdown checklists
+Author-email: menisadi <menisadi@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Meni
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/menisadi/checkmarks
+Project-URL: Issues, https://github.com/menisadi/checkmarks/issues
+Keywords: cli,markdown,checklists
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Checkmarks
+
+A small command-line dashboard for your progress. Point it at a folder of Markdown files (books, courses, tutorials) and get one progress bar per file.
+
+```
+$ checkmarks ~/progress
+Thinking, Fast and Slow  [████------]  143/320 pages   45%
+Gödel, Escher, Bach      [██--------]  180/777 pages   23%
+Rust tutorial            [████------]   12/28  tasks   43%
+NN hands-on              [██--------]    2/8   tasks   25%
+```
+
+Your Markdown files are the source of truth: checkmarks only reads and reports. It never changes your files and keeps no state of its own.
+
+## Installation
+
+### Option 1: Install via PyPI (Recommended)
+```bash
+pip install checkmarks
+```
+
+### Option 2: Install from source
+
+1. Make sure you have Python 3.11+ installed.
+2. Clone or download this repository.
+```bash
+git clone https://github.com/menisadi/checkmarks.git
+cd checkmarks
+pip install .
+```
+
+## Usage
+
+```bash
+checkmarks todo.md               # one file
+checkmarks ~/progress            # every .md file in a folder
+checkmarks -r ~/progress         # ...and in its subfolders
+checkmarks a.md b.md notes/      # any mix of files and folders
+fd -e md | checkmarks -          # read paths from stdin
+checkmarks                       # $CHECKMARKS_DIR if set, else the current folder
+```
+
+In folders, files ending in `.md` or `.markdown` are read, sorted by path. With `-r`, folders whose names start with `.` (like `.git`) are skipped.
+
+## File format
+
+### Checklists
+
+By default, checkmarks counts checkboxes:
+
+```markdown
+# My Todo List
+
+- [ ] Buy groceries
+- [x] Write blog post
+  - [X] Nested items count too
+1. [ ] Ordered lists work as well
+```
+
+- `[x]` and `[X]` are done; `[ ]` is pending.
+- List items can start with `-`, `*`, `+`, `1.` or `1)`.
+- Checkboxes inside fenced code blocks are ignored.
+
+### Counters
+
+For things that aren't a list of tasks, like the pages of a book, add frontmatter with a `progress` key. It replaces the checkbox count:
+
+```markdown
+---
+progress: 143/320
+unit: pages
+---
+# Dune
+```
+
+Supported keys:
+
+| Key        | Meaning                                                            |
+|------------|--------------------------------------------------------------------|
+| `progress` | `done/total`, e.g. `143/320`                                       |
+| `unit`     | Label after the count (default `tasks`, or `units` with `progress`) |
+| `title`    | Row title                                                          |
+
+`unit` and `title` also work in checklist files. Other keys are ignored.
+
+### Titles
+
+The row title is the frontmatter `title`, else the first `# Heading`, else the filename.
+
+## Output
+
+On a terminal, checkmarks prints the aligned table shown above. Rows at 100% are green; set `NO_COLOR` or pass `--no-color` to turn colour off.
+
+When output is piped, it switches to tab-separated rows with no header:
+
+```
+title  done  total  pct  unit  mode  status  path
+```
+
+Use `--json` for a JSON array:
+
+```bash
+$ checkmarks --json dune.md
+[
+  {
+    "title": "Dune",
+    "done": 143,
+    "total": 320,
+    "pct": 44.7,
+    "unit": "pages",
+    "mode": "counter",
+    "status": "ok",
+    "path": "dune.md"
+  }
+]
+```
+
+`status` is `ok`, `empty` (no checkboxes) or `error` (e.g. an invalid `progress` value). Problems are reported on stderr, and the row is still shown.
+
+Empty files found in folders are hidden; pass `--all` to show them. Files you name directly are always shown.
+
+## Options
+
+| Option                       | Description                                 |
+|------------------------------|---------------------------------------------|
+| `-r`, `--recursive`          | Descend into subfolders                     |
+| `--all`                      | Show empty files found in folders           |
+| `--format {pretty,tsv,json}` | Choose the output format                    |
+| `--json`                     | Same as `--format json`                     |
+| `--no-color`                 | Disable colour                              |
+| `-v`, `--verbose`            | Also warn about files with no checkboxes    |
+
+Exit code is `0` if at least one file has progress to show, `1` if none does, and `2` for usage errors.
+
+## Upgrading from 0.1
+
+- Output is now a table row per file instead of the old "📊 Progress for:" block.
+- Python 3.11 or newer is required.
+- Plain checklist files need no changes.
+
+## Contributing
+
+Feel free to submit issues or pull requests. This is a small tool, so contributions are always welcome.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

checkmarks-0.2.0/README.md

@@ -0,0 +1,146 @@
+# Checkmarks
+
+A small command-line dashboard for your progress. Point it at a folder of Markdown files (books, courses, tutorials) and get one progress bar per file.
+
+```
+$ checkmarks ~/progress
+Thinking, Fast and Slow  [████------]  143/320 pages   45%
+Gödel, Escher, Bach      [██--------]  180/777 pages   23%
+Rust tutorial            [████------]   12/28  tasks   43%
+NN hands-on              [██--------]    2/8   tasks   25%
+```
+
+Your Markdown files are the source of truth: checkmarks only reads and reports. It never changes your files and keeps no state of its own.
+
+## Installation
+
+### Option 1: Install via PyPI (Recommended)
+```bash
+pip install checkmarks
+```
+
+### Option 2: Install from source
+
+1. Make sure you have Python 3.11+ installed.
+2. Clone or download this repository.
+```bash
+git clone https://github.com/menisadi/checkmarks.git
+cd checkmarks
+pip install .
+```
+
+## Usage
+
+```bash
+checkmarks todo.md               # one file
+checkmarks ~/progress            # every .md file in a folder
+checkmarks -r ~/progress         # ...and in its subfolders
+checkmarks a.md b.md notes/      # any mix of files and folders
+fd -e md | checkmarks -          # read paths from stdin
+checkmarks                       # $CHECKMARKS_DIR if set, else the current folder
+```
+
+In folders, files ending in `.md` or `.markdown` are read, sorted by path. With `-r`, folders whose names start with `.` (like `.git`) are skipped.
+
+## File format
+
+### Checklists
+
+By default, checkmarks counts checkboxes:
+
+```markdown
+# My Todo List
+
+- [ ] Buy groceries
+- [x] Write blog post
+  - [X] Nested items count too
+1. [ ] Ordered lists work as well
+```
+
+- `[x]` and `[X]` are done; `[ ]` is pending.
+- List items can start with `-`, `*`, `+`, `1.` or `1)`.
+- Checkboxes inside fenced code blocks are ignored.
+
+### Counters
+
+For things that aren't a list of tasks, like the pages of a book, add frontmatter with a `progress` key. It replaces the checkbox count:
+
+```markdown
+---
+progress: 143/320
+unit: pages
+---
+# Dune
+```
+
+Supported keys:
+
+| Key        | Meaning                                                            |
+|------------|--------------------------------------------------------------------|
+| `progress` | `done/total`, e.g. `143/320`                                       |
+| `unit`     | Label after the count (default `tasks`, or `units` with `progress`) |
+| `title`    | Row title                                                          |
+
+`unit` and `title` also work in checklist files. Other keys are ignored.
+
+### Titles
+
+The row title is the frontmatter `title`, else the first `# Heading`, else the filename.
+
+## Output
+
+On a terminal, checkmarks prints the aligned table shown above. Rows at 100% are green; set `NO_COLOR` or pass `--no-color` to turn colour off.
+
+When output is piped, it switches to tab-separated rows with no header:
+
+```
+title  done  total  pct  unit  mode  status  path
+```
+
+Use `--json` for a JSON array:
+
+```bash
+$ checkmarks --json dune.md
+[
+  {
+    "title": "Dune",
+    "done": 143,
+    "total": 320,
+    "pct": 44.7,
+    "unit": "pages",
+    "mode": "counter",
+    "status": "ok",
+    "path": "dune.md"
+  }
+]
+```
+
+`status` is `ok`, `empty` (no checkboxes) or `error` (e.g. an invalid `progress` value). Problems are reported on stderr, and the row is still shown.
+
+Empty files found in folders are hidden; pass `--all` to show them. Files you name directly are always shown.
+
+## Options
+
+| Option                       | Description                                 |
+|------------------------------|---------------------------------------------|
+| `-r`, `--recursive`          | Descend into subfolders                     |
+| `--all`                      | Show empty files found in folders           |
+| `--format {pretty,tsv,json}` | Choose the output format                    |
+| `--json`                     | Same as `--format json`                     |
+| `--no-color`                 | Disable colour                              |
+| `-v`, `--verbose`            | Also warn about files with no checkboxes    |
+
+Exit code is `0` if at least one file has progress to show, `1` if none does, and `2` for usage errors.
+
+## Upgrading from 0.1
+
+- Output is now a table row per file instead of the old "📊 Progress for:" block.
+- Python 3.11 or newer is required.
+- Plain checklist files need no changes.
+
+## Contributing
+
+Feel free to submit issues or pull requests. This is a small tool, so contributions are always welcome.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.

checkmarks-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "checkmarks"
+version = "0.2.0"
+description = "Progress dashboard for Markdown checklists"
+authors = [
+  { name = "menisadi", email = "menisadi@gmail.com" }
+]
+
+readme = "README.md"
+
+license = { file = "LICENSE" }
+
+keywords = ["cli", "markdown", "checklists"]
+
+requires-python = ">=3.11"
+
+dependencies = []
+
+[project.scripts]
+checkmarks = "checkmarks.cli:main"
+
+[project.urls]
+"Homepage" = "https://github.com/menisadi/checkmarks"
+"Issues" = "https://github.com/menisadi/checkmarks/issues"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "ty"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"

checkmarks-0.2.0/src/checkmarks/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("checkmarks")

checkmarks-0.2.0/src/checkmarks/cli.py

@@ -0,0 +1,85 @@
+import argparse
+import os
+import shutil
+import sys
+
+from checkmarks.collect import collect
+from checkmarks.parse import Item, parse_file
+from checkmarks.render import render_json, render_pretty, render_tsv
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="checkmarks", description="Show progress for Markdown checklists"
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        metavar="PATH",
+        help="files or directories to read; - reads paths from stdin "
+        "(default: $CHECKMARKS_DIR, else the current directory)",
+    )
+    parser.add_argument(
+        "-r", "--recursive", action="store_true", help="descend into subdirectories"
+    )
+    parser.add_argument(
+        "--all", action="store_true", help="show empty files found in directories"
+    )
+    fmt = parser.add_mutually_exclusive_group()
+    fmt.add_argument(
+        "--format",
+        choices=["pretty", "tsv", "json"],
+        help="output format (default: pretty on a terminal, else tsv)",
+    )
+    fmt.add_argument(
+        "--json",
+        action="store_const",
+        const="json",
+        dest="format",
+        help="same as --format json",
+    )
+    parser.add_argument("--no-color", action="store_true", help="disable colour")
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="warn about empty files"
+    )
+    return parser
+
+
+def warn(message: str) -> None:
+    print(f"checkmarks: {message}", file=sys.stderr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point for the CLI. Returns the exit code."""
+    args = build_parser().parse_args(argv)
+
+    sources, warnings = collect(args.paths, args.recursive, sys.stdin, os.environ)
+    for warning in warnings:
+        warn(warning)
+
+    items: list[Item] = []
+    for source in sources:
+        item = parse_file(source.path)
+        if item.status == "error" or (item.status == "empty" and args.verbose):
+            warn(f"{item.path}: {item.message}")
+        if item.status == "empty" and not source.explicit and not args.all:
+            continue
+        items.append(item)
+
+    is_tty = sys.stdout.isatty()
+    fmt = args.format or ("pretty" if is_tty else "tsv")
+    if fmt == "json":
+        output = render_json(items)
+    elif fmt == "tsv":
+        output = render_tsv(items)
+    else:
+        color = is_tty and not args.no_color and not os.environ.get("NO_COLOR")
+        width = shutil.get_terminal_size().columns
+        output = render_pretty(items, width, color)
+    sys.stdout.write(output)
+
+    return 0 if any(item.status == "ok" for item in items) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

checkmarks-0.2.0/src/checkmarks/collect.py

@@ -0,0 +1,74 @@
+import os
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+MARKDOWN_SUFFIXES = {".md", ".markdown"}
+
+
+@dataclass
+class Source:
+    path: Path
+    explicit: bool
+
+
+def expand_dir(directory: Path, recursive: bool) -> list[Path]:
+    """Returns the Markdown files in a directory, sorted by path."""
+    found: list[Path] = []
+    for root, dirnames, filenames in os.walk(directory):
+        if recursive:
+            dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+        else:
+            dirnames[:] = []
+        root_path = Path(root)
+        found.extend(
+            root_path / name
+            for name in filenames
+            if Path(name).suffix.lower() in MARKDOWN_SUFFIXES
+        )
+    return sorted(found)
+
+
+def iter_args(paths: list[str], stdin: TextIO, env: Mapping[str, str]) -> Iterator[str]:
+    """Yields path arguments, expanding `-` and applying the no-argument default."""
+    if not paths:
+        yield env.get("CHECKMARKS_DIR") or "."
+        return
+
+    for arg in paths:
+        if arg == "-":
+            yield from (line.strip() for line in stdin if line.strip())
+        else:
+            yield arg
+
+
+def collect(
+    paths: list[str], recursive: bool, stdin: TextIO, env: Mapping[str, str]
+) -> tuple[list[Source], list[str]]:
+    """Resolves path arguments into sources, plus warnings for bad paths."""
+    sources: list[Source] = []
+    warnings: list[str] = []
+    seen: dict[Path, Source] = {}
+
+    def add(path: Path, explicit: bool) -> None:
+        key = path.resolve()
+        if key in seen:
+            # The first position wins, but an explicit mention always counts
+            seen[key].explicit = seen[key].explicit or explicit
+            return
+        source = Source(path, explicit)
+        seen[key] = source
+        sources.append(source)
+
+    for arg in iter_args(paths, stdin, env):
+        path = Path(arg)
+        if path.is_dir():
+            for file in expand_dir(path, recursive):
+                add(file, explicit=False)
+        elif path.exists():
+            add(path, explicit=True)
+        else:
+            warnings.append(f"{arg}: no such file or directory")
+
+    return sources, warnings

checkmarks-0.2.0/src/checkmarks/parse.py

@@ -0,0 +1,141 @@
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+CHECKBOX_RE = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s+\[( |x|X)\](?:\s|$)")
+FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
+HEADING_RE = re.compile(r"^#\s+(.+)")
+PROGRESS_RE = re.compile(r"^(\d+)\s*/\s*(\d+)$")
+
+
+@dataclass
+class Item:
+    path: Path
+    title: str
+    done: int | None
+    total: int | None
+    unit: str
+    mode: Literal["checklist", "counter"]
+    status: Literal["ok", "empty", "error"]
+    message: str | None = None
+
+
+def unfenced_lines(lines: Iterable[str]) -> Iterator[str]:
+    """Yields the lines that are outside fenced code blocks."""
+    fence: str | None = None
+
+    for line in lines:
+        if fence is not None:
+            # A fence closes on the same character, at least as long as the opener
+            if re.fullmatch(rf"\s*{re.escape(fence[0])}{{{len(fence)},}}\s*", line):
+                fence = None
+            continue
+
+        fence_match = FENCE_RE.match(line)
+        if fence_match:
+            fence = fence_match.group(1)
+            continue
+
+        yield line
+
+
+def count_checkboxes(text: str) -> tuple[int, int]:
+    """Returns (done, total) checkbox counts, ignoring fenced code blocks."""
+    done = 0
+    total = 0
+
+    for line in unfenced_lines(text.splitlines()):
+        box_match = CHECKBOX_RE.match(line)
+        if box_match:
+            total += 1
+            if box_match.group(1) in ("x", "X"):
+                done += 1
+
+    return done, total
+
+
+def find_heading(lines: Iterable[str]) -> str | None:
+    """Returns the first level-1 heading outside fenced code blocks."""
+    for line in unfenced_lines(lines):
+        heading_match = HEADING_RE.match(line)
+        if heading_match:
+            return heading_match.group(1).strip()
+    return None
+
+
+def parse_frontmatter(lines: list[str]) -> tuple[dict[str, str], int]:
+    """Returns (frontmatter keys, index of the first body line)."""
+    if not lines or lines[0] != "---":
+        return {}, 0
+
+    try:
+        end = lines.index("---", 1)
+    except ValueError:
+        # No closing delimiter: the file has no frontmatter
+        return {}, 0
+
+    meta: dict[str, str] = {}
+    for line in lines[1:end]:
+        key, sep, value = line.partition(":")
+        if not sep:
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        meta[key.strip()] = value
+
+    return meta, end + 1
+
+
+def parse_progress(value: str) -> tuple[int, int] | str:
+    """Returns (done, total), or an error message if the value is invalid."""
+    progress_match = PROGRESS_RE.match(value)
+    if not progress_match:
+        return f"unparseable progress: {value!r}"
+
+    done, total = int(progress_match.group(1)), int(progress_match.group(2))
+    if total == 0:
+        return "progress total is 0"
+    if done > total:
+        return f"progress {done}/{total} exceeds total"
+    return done, total
+
+
+def parse_file(path: Path) -> Item:
+    """Parses a Markdown file into an Item."""
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError) as e:
+        return Item(
+            path=path,
+            title=path.stem,
+            done=None,
+            total=None,
+            unit="tasks",
+            mode="checklist",
+            status="error",
+            message=str(e),
+        )
+
+    lines = text.splitlines()
+    meta, body_start = parse_frontmatter(lines)
+    body = lines[body_start:]
+    title = meta.get("title") or find_heading(body) or path.stem
+
+    if "progress" in meta:
+        unit = meta.get("unit") or "units"
+        progress = parse_progress(meta["progress"])
+        if isinstance(progress, str):
+            return Item(path, title, None, None, unit, "counter", "error", progress)
+        done, total = progress
+        return Item(path, title, done, total, unit, "counter", "ok")
+
+    unit = meta.get("unit") or "tasks"
+    done, total = count_checkboxes("\n".join(body))
+    if total == 0:
+        return Item(
+            path, title, None, None, unit, "checklist", "empty", "no checkboxes found"
+        )
+    return Item(path, title, done, total, unit, "checklist", "ok")