gemba-cli 0.1.0__py3-none-any.whl

gemba/commands/list.py

@@ -0,0 +1,51 @@
+"""`gemba list`: validate the filters, scan the workstream folders and print one JSON document."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import sys
+from pathlib import Path
+
+from gemba import config
+from gemba.commands import selection
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "list",
+        help="list tasks as one JSON document",
+        description=(
+            "Scan the workstream folders of gemba.yaml, validate every task file and print one JSON object: "
+            "`tasks`, the matching task records, and `problems`, the files that are not valid tasks and the "
+            "metadata values that are not of the type their field declares. Values of one filter are "
+            "alternatives; different filters must all match. Date ranges and bounds are inclusive."
+        ),
+    )
+    selection.add_options(parser)
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail(str(exc))
+
+    scope, filters, errors = selection.build(args, gemba_config)
+    if errors:
+        return fail("nothing listed:\n" + "\n".join(f"- {error}" for error in errors))
+
+    found, problems = selection.select(gemba_config, scope, filters)
+    document = {
+        "tasks": [dataclasses.asdict(task) for task in found],
+        "problems": [dataclasses.asdict(problem) for problem in problems],
+    }
+    print(selection.dump(document))
+    return 0
+
+
+def fail(message: str) -> int:
+    print(f"gemba list: {message}", file=sys.stderr)
+    return 1

gemba/commands/mark.py

@@ -0,0 +1,91 @@
+"""`gemba mark`: move the status of a task after its creation."""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+
+from gemba import config, tasks, values
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "mark",
+        help="move the status of a task",
+        description=(
+            f"Set the status of the task with this ref to one of {', '.join(tasks.STATUSES)}. Reaching done "
+            "writes done_at, leaving done removes it, and updated_at moves to the date when it is later. Only "
+            "the frontmatter is rewritten: the body, the harness of the task and git are not touched."
+        ),
+    )
+    parser.add_argument("ref", help="ref of the task, such as SUP-1")
+    parser.add_argument("status", help=f"the status to move to: {', '.join(tasks.STATUSES)}")
+    parser.add_argument(
+        "--date",
+        metavar="YYYY-MM-DD",
+        help="the day of the transition (default: today); not after today, not before the task was created",
+    )
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail(str(exc))
+
+    errors = []
+    if problem := tasks.status_problem(args.status):
+        errors.append(problem)
+    try:
+        task = tasks.find_by_ref(gemba_config.root, gemba_config.workstreams, args.ref)
+    except tasks.TaskError as exc:
+        task = None
+        errors.append(str(exc))
+    else:
+        if task is None:
+            errors.append(f"no task has ref '{args.ref}' under {tasks.TASKS_DIR}/, archives included")
+        elif task.archived:
+            errors.append(
+                f"{task.ref} is archived ({task.path}): move the file out of {tasks.ARCHIVE_DIR}/ before marking it"
+            )
+    today = datetime.date.today()
+    day = today if args.date is None else values.iso_date(args.date)
+    if day is None:
+        errors.append(f"invalid date '{args.date}': use YYYY-MM-DD")
+    # Without a task there is no creation date to compare with, only today.
+    elif problem := tasks.date_problem(day, task.date if task is not None else datetime.date.min, today):
+        errors.append(problem)
+    if errors:
+        return fail("task not marked:\n" + "\n".join(f"- {error}" for error in errors))
+    assert task is not None and day is not None, "every failed check appended an error"
+
+    task_file = gemba_config.root / task.path
+    try:
+        text, moved = tasks.transition(task_file.read_bytes().decode("utf-8"), args.status, day)
+    except tasks.TaskError as exc:
+        return fail(f"task not marked: {task.path}: {exc}")
+    if moved.changed:
+        task_file.write_bytes(text.encode("utf-8"))
+    print(task.path)
+    if not moved.changed:
+        print(f"status: {moved.old_status}, left as it was")
+        return 0
+    print(f"status: {moved.old_status} -> {moved.new_status}")
+    if moved.done_at is not None:
+        print(f"done_at: {moved.done_at.isoformat()}")
+    elif moved.done_at_removed:
+        print("done_at: removed")
+    if moved.new_updated_at == moved.old_updated_at:
+        print(f"updated_at: {moved.old_updated_at.isoformat()} (unchanged)")
+    else:
+        print(f"updated_at: {moved.old_updated_at.isoformat()} -> {moved.new_updated_at.isoformat()}")
+    return 0
+
+
+def fail(message: str) -> int:
+    print(f"gemba mark: {message}", file=sys.stderr)
+    return 1

gemba/commands/record.py

@@ -0,0 +1,113 @@
+"""`gemba record`: write the drafted update of a day into the task of a harness."""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+import textwrap
+from pathlib import Path, PurePosixPath
+
+from gemba import config, harness, skills, tasks, values
+from gemba.commands import harness as harness_command
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "record",
+        help="write the drafted update of a day into the task of a harness",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description=textwrap.fill(
+            f"Write the bullets of a draft under ### YYYY-MM-DD in the {tasks.UPDATES_HEADING} section of the task "
+            "of this harness, appending them when that day already has a subsection, move updated_at to the day "
+            "when it is later, and delete the draft. The path of the draft is relative to the harness root. "
+            "Nothing is committed.",
+            width=79,
+        ),
+    )
+    parser.add_argument(
+        "file",
+        help=f"the draft, such as update.md: lines starting with '{tasks.BULLET_PREFIX}', continued by lines "
+        f"indented by two spaces",
+    )
+    parser.add_argument(
+        "--date",
+        metavar="YYYY-MM-DD",
+        help="the day the update is about (default: today); not after today, not before the task was created",
+    )
+    harness_command.add_location(parser)
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        folder = harness_command.locate(args.harness)
+        gemba_config = config.load(root=args.root, cwd=folder)
+        identity = harness.read_config(folder, list(skills.PROVIDERS))
+    except (harness.HarnessError, config.ConfigError) as exc:
+        return fail(str(exc))
+
+    root = gemba_config.root
+    task_file = root / identity.task
+    if not task_file.is_file():
+        return fail(
+            f"record not done: the task file {identity.task} named by {harness.CONFIG_FILENAME} "
+            f"was not found there, under {root}"
+        )
+    archived = PurePosixPath(identity.task).parent.name == tasks.ARCHIVE_DIR
+    try:
+        task = tasks.read(task_file, root, identity.workstream, archived)
+    except tasks.TaskError as exc:
+        return fail(f"record not done: {identity.task} is not a valid task: {exc}")
+    text = task_file.read_bytes().decode("utf-8")
+
+    today = datetime.date.today()
+    errors = []
+    day = today if args.date is None else values.iso_date(args.date)
+    if day is None:
+        errors.append(f"invalid date '{args.date}': use YYYY-MM-DD")
+    elif problem := tasks.date_problem(day, task.date, today):
+        errors.append(problem)
+    bullets, draft_errors = read_draft(folder, args.file)
+    errors.extend(f"{args.file} {problem}" for problem in draft_errors)
+    _frontmatter, body = tasks.split(text)
+    if problem := tasks.updates_problem(body):
+        errors.append(f"{task.path} {problem}")
+    if errors:
+        return fail("record not done:\n" + "\n".join(f"- {error}" for error in errors))
+    assert day is not None, "an invalid date appended an error"
+
+    recorded, previous, updated_at = tasks.record(text, task.date, today, day, bullets)
+    task_file.write_bytes(recorded.encode("utf-8"))
+    try:
+        (folder / args.file).unlink()
+    except OSError as exc:
+        return fail(
+            f"{task.path} is recorded but the draft {args.file} could not be deleted: {exc.strerror}; "
+            "delete it by hand and do not record it again, which would write its bullets twice"
+        )
+    print(task.path)
+    if updated_at == previous:
+        print(f"updated_at: {previous.isoformat()} (unchanged)")
+    else:
+        print(f"updated_at: {previous.isoformat()} -> {updated_at.isoformat()}")
+    return 0
+
+
+def read_draft(folder: Path, given: str) -> tuple[list[str], list[str]]:
+    """The bullet lines of the draft at `given`, relative to the harness root, and every problem found with it."""
+    path = (folder / given).resolve()
+    if not path.is_relative_to(folder):
+        return [], ["is not inside the harness (paths are relative to the harness root)"]
+    if not path.is_file():
+        return [], ["is not a file" if path.exists() else "does not exist"]
+    try:
+        text = path.read_bytes().decode("utf-8")
+    except UnicodeDecodeError:
+        return [], ["is not UTF-8 text"]
+    return tasks.parse_bullets(text)
+
+
+def fail(message: str) -> int:
+    print(f"gemba record: {message}", file=sys.stderr)
+    return 1

gemba/commands/report.py

@@ -0,0 +1,80 @@
+"""`gemba report`: select tasks as `gemba list` does, then count, group and sum them in one JSON document."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import sys
+from pathlib import Path
+
+from gemba import config, report
+from gemba.commands import selection
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "report",
+        help="count, group and sum the selected tasks as one JSON document",
+        description=(
+            "Select tasks with the filters of gemba list, then print one JSON object: `by` and `sum` as given, "
+            "`groups`, one entry per combination of grouping values with its task count, refs and sums, "
+            "`total`, over every selected task counted once, and `problems`, as gemba list reports them. "
+            "Sums are exact; a task without a number to add is counted as missing."
+        ),
+    )
+    selection.add_options(parser)
+    parser.add_argument(
+        "--by",
+        dest="groupings",
+        action="append",
+        default=[],
+        metavar="KEY",
+        help="group by workstream, status, or a declared text or boolean field; repeat to group within groups",
+    )
+    parser.add_argument(
+        "--sum",
+        dest="sums",
+        action="append",
+        default=[],
+        metavar="KEY",
+        help="add up a declared number field per group and in the total; repeat for several",
+    )
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail(str(exc))
+
+    scope, filters, errors = selection.build(args, gemba_config)
+    types = gemba_config.types()
+    errors.extend(report.problems(args.groupings, args.sums, types))
+    if errors:
+        return fail("nothing reported:\n" + "\n".join(f"- {error}" for error in errors))
+
+    found, problems = selection.select(gemba_config, scope, filters)
+    result = report.aggregate(found, args.groupings, args.sums, types, list(gemba_config.workstreams))
+    document = {
+        "by": args.groupings,
+        "sum": args.sums,
+        "groups": [
+            {"key": group.key, "tasks": group.tasks, "refs": group.refs, "sums": sums(group.sums)}
+            for group in result.groups
+        ],
+        "total": {"tasks": result.tasks, "sums": sums(result.sums)},
+        "problems": [dataclasses.asdict(problem) for problem in problems],
+    }
+    print(selection.dump(document))
+    return 0
+
+
+def sums(found: dict[str, report.Sum]) -> dict[str, dict[str, object]]:
+    return {key: {"total": total.total, "missing": total.missing} for key, total in found.items()}
+
+
+def fail(message: str) -> int:
+    print(f"gemba report: {message}", file=sys.stderr)
+    return 1

gemba/commands/selection.py

@@ -0,0 +1,170 @@
+"""The selection shared by `gemba list` and `gemba report`: its options, their validation and the scan."""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+from dataclasses import dataclass
+
+from gemba import config, metadata, tasks, values
+
+# Destination of each date option, named after the Filters field it fills.
+DATE_OPTIONS = (
+    ("created_from", "--from"),
+    ("created_to", "--to"),
+    ("updated_from", "--updated-from"),
+    ("updated_to", "--updated-to"),
+    ("done_from", "--done-from"),
+    ("done_to", "--done-to"),
+)
+
+
+@dataclass(frozen=True)
+class Scope:
+    """The workstream folders a selection scans; unless they were filtered, every stray entry under tasks/ too."""
+
+    workstreams: tuple[str, ...]
+    include_archived: bool
+    filtered: bool
+
+
+def add_options(parser: argparse.ArgumentParser) -> None:
+    """Register the selection filters on the parser of a command."""
+    parser.add_argument(
+        "--workstream",
+        dest="workstreams",
+        action="append",
+        default=[],
+        metavar="ID",
+        help="workstream identifier from gemba.yaml; repeat for several (default: every workstream)",
+    )
+    parser.add_argument(
+        "--status",
+        dest="statuses",
+        action="append",
+        default=[],
+        metavar="STATUS",
+        help="open, in-progress, blocked or done; repeat for several (default: every status)",
+    )
+    parser.add_argument("--ref", help="exact task ref, such as SUP-1")
+    parser.add_argument(
+        "--from", dest="created_from", metavar="YYYY-MM-DD", help="created on or after (the filename date)"
+    )
+    parser.add_argument(
+        "--to", dest="created_to", metavar="YYYY-MM-DD", help="created on or before (the filename date)"
+    )
+    parser.add_argument("--updated-from", dest="updated_from", metavar="YYYY-MM-DD", help="updated_at on or after")
+    parser.add_argument("--updated-to", dest="updated_to", metavar="YYYY-MM-DD", help="updated_at on or before")
+    parser.add_argument(
+        "--done-from", dest="done_from", metavar="YYYY-MM-DD", help="done_at on or after; tasks without it never match"
+    )
+    parser.add_argument(
+        "--done-to", dest="done_to", metavar="YYYY-MM-DD", help="done_at on or before; tasks without it never match"
+    )
+    parser.add_argument("--include-archived", action="store_true", help="also read the archive/ folders")
+    parser.add_argument(
+        "--where",
+        dest="conditions",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help=(
+            "metadata condition on a declared key, the value written by the type of the key (null finds unset "
+            "values); matches an equal value or a list containing it; repeat a key for alternatives"
+        ),
+    )
+    parser.add_argument(
+        "--where-from",
+        dest="lower",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="lower bound, included, on a number or date key; one per key; null values never match",
+    )
+    parser.add_argument(
+        "--where-to",
+        dest="upper",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="upper bound, included, on a number or date key; one per key; null values never match",
+    )
+
+
+def build(args: argparse.Namespace, gemba_config: config.Config) -> tuple[Scope, tasks.Filters, list[str]]:
+    """The scan scope and the filters of the options, and every invalid filter."""
+    errors = []
+    workstreams = list(dict.fromkeys(args.workstreams))
+    for workstream in workstreams:
+        if workstream not in gemba_config.workstreams:
+            errors.append(
+                f"unknown workstream '{workstream}' (valid workstreams: {', '.join(gemba_config.workstreams)})"
+            )
+    for status in dict.fromkeys(args.statuses):
+        if problem := tasks.status_problem(status):
+            errors.append(problem)
+    dates: dict[str, datetime.date | None] = {}
+    for dest, option in DATE_OPTIONS:
+        text = getattr(args, dest)
+        dates[dest] = None if text is None else values.iso_date(text)
+        if text is not None and dates[dest] is None:
+            errors.append(f"invalid date '{text}' for {option}: use YYYY-MM-DD")
+    conditions, condition_errors = metadata.parse_conditions(
+        args.conditions, args.lower, args.upper, gemba_config.types()
+    )
+    errors.extend(condition_errors)
+
+    # A workstream filter is the scan scope: no other folder is read or reported.
+    scope = Scope(tuple(workstreams or gemba_config.workstreams), args.include_archived, bool(workstreams))
+    filters = tasks.Filters(
+        statuses=args.statuses,
+        ref=args.ref,
+        created_from=dates["created_from"],
+        created_to=dates["created_to"],
+        updated_from=dates["updated_from"],
+        updated_to=dates["updated_to"],
+        done_from=dates["done_from"],
+        done_to=dates["done_to"],
+        metadata=conditions,
+        schemas={
+            workstream: [field.name for field in gemba_config.effective_schema(workstream)]
+            for workstream in gemba_config.workstreams
+        },
+    )
+    return scope, filters, errors
+
+
+def select(
+    gemba_config: config.Config, scope: Scope, filters: tasks.Filters
+) -> tuple[list[tasks.Task], list[tasks.Problem]]:
+    """The tasks of the scope that pass the filters, and the problems of the scan.
+
+    Every value of a scanned task whose key has a declared type and that is not of that
+    type is a problem too, whatever the filters, and its task is still selected when it
+    matches.
+    """
+    found, problems = tasks.scan(
+        gemba_config.root,
+        scope.workstreams,
+        scope.include_archived,
+        configured=None if scope.filtered else list(gemba_config.workstreams),
+    )
+    types = gemba_config.types()
+    for task in found:
+        for key, value in task.metadata.items():
+            if key in types and (problem := metadata.value_problem(types[key], value)):
+                problems.append(tasks.Problem(task.path, f"metadata value of '{key}' {problem}"))
+    problems.sort(key=lambda problem: problem.path)
+    return [task for task in found if tasks.matches(task, filters)], problems
+
+
+def dump(document: object) -> str:
+    """A document as `list` and `report` print it: indented JSON, dates as ISO strings."""
+    return json.dumps(document, indent=2, ensure_ascii=False, default=_iso)
+
+
+def _iso(value: object) -> str:
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    raise TypeError(f"{type(value).__name__} is not JSON serializable")

gemba/commands/set.py

@@ -0,0 +1,81 @@
+"""`gemba set`: write metadata values of a task after its creation."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from gemba import config, metadata, tasks
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "set",
+        help="set metadata values of a task",
+        description=(
+            "Write metadata values into the task with this ref, archives included, each converted by the "
+            "declared type of its field. The metadata map is completed with the keys of the current schema, "
+            "as null, and keeps the keys the schema no longer declares. Only the metadata is rewritten: "
+            "updated_at, the body, the harness of the task and git are not touched."
+        ),
+    )
+    parser.add_argument("ref", help="ref of the task, such as SUP-1")
+    parser.add_argument(
+        "assignments",
+        nargs="+",
+        metavar="KEY=VALUE",
+        help=(
+            "key=value sets a value written by the type of its field, key=null clears it, and key+=number adds "
+            "to a number field, null counting as zero; repeat a key of a text field to set a list"
+        ),
+    )
+    parser.add_argument("--root", type=Path, help="tasks repo root (default: walk up to the nearest gemba.yaml)")
+    parser.set_defaults(handler=run)
+
+
+def run(args: argparse.Namespace) -> int:
+    try:
+        gemba_config = config.load(root=args.root)
+    except config.ConfigError as exc:
+        return fail(str(exc))
+
+    assignments, errors = metadata.parse_assignments(args.assignments, allow_add=True)
+    try:
+        task = tasks.find_by_ref(gemba_config.root, gemba_config.workstreams, args.ref)
+    except tasks.TaskError as exc:
+        task = None
+        errors.append(str(exc))
+    else:
+        if task is None:
+            errors.append(f"no task has ref '{args.ref}' under {tasks.TASKS_DIR}/, archives included")
+    assigned = None
+    if task is not None:
+        schema = gemba_config.effective_schema(task.workstream)
+        assigned = metadata.assign(schema, task.metadata, assignments, f"'{task.workstream}'")
+        errors.extend(assigned.problems)
+    if errors:
+        return fail("metadata not set:\n" + "\n".join(f"- {error}" for error in errors))
+    assert task is not None and assigned is not None, "every failed check appended an error"
+
+    if assigned.changed:
+        task_file = gemba_config.root / task.path
+        try:
+            text = tasks.set_metadata(task_file.read_bytes().decode("utf-8"), assigned.values)
+        except tasks.TaskError as exc:
+            return fail(f"metadata not set: {task.path}: {exc}")
+        task_file.write_bytes(text.encode("utf-8"))
+    print(task.path)
+    for change in assigned.changes:
+        if change.added:
+            print(f"{change.key}: added as null")
+        elif change.changed:
+            print(f"{change.key}: {metadata.show(change.old)} -> {metadata.show(change.new)}")
+        else:
+            print(f"{change.key}: {metadata.show(change.new)} (unchanged)")
+    return 0
+
+
+def fail(message: str) -> int:
+    print(f"gemba set: {message}", file=sys.stderr)
+    return 1