taskflow-git 0.3.0__py3-none-any.whl

taskflow/config.py

@@ -0,0 +1,195 @@
+"""
+config.py — project root discovery and .taskflow.yml loading.
+
+Everything resolves relative to wherever .taskflow.yml lives. Walk up
+from cwd until we find it, or fail clearly. This is the only place that
+knows about the config structure — everything else asks this module.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+CONFIG_FILE = ".taskflow.yml"
+
+# defaults used when states section is missing or partially specified
+STATE_DEFAULTS: dict[str, dict] = {
+    "now": {"file": "backlog/0-now.md", "icon": "▶"},
+    "blocked": {"file": "backlog/1-blocked.md", "icon": "⊘"},
+    "paused": {"file": "backlog/2-paused.md", "icon": "⏸"},
+    "next": {"file": "backlog/3-next.md", "icon": "◈"},
+    "later": {"file": "backlog/4-later.md", "icon": "◇"},
+    "done": {"file": "backlog/done.md", "icon": "✓"},
+}
+
+# the order transitions are defined matters for help text and validation
+WORKFLOW_TRANSITIONS: dict[str, tuple[str, str, str]] = {
+    "promote": ("later", "next", "promote"),
+    "start": ("next", "now", "start"),
+    "block": ("now", "blocked", "block"),
+    "unblock": ("blocked", "now", "unblock"),
+    "pause": ("now", "paused", "pause"),
+    "unpause": ("paused", "now", "unpause"),
+    "backlog": ("now", "next", "backlog"),
+}
+
+
+class TaskflowConfig:
+    """
+    Loaded config for a taskflow project. All path resolution goes through here
+    so nothing else has to think about absolute vs relative.
+    """
+
+    def __init__(self, root: Path, data: dict) -> None:
+        self.root = root
+        self._data = data
+
+    # --- state resolution ---
+
+    def state(self, name: str) -> dict:
+        """Return merged config for a state — user values over defaults."""
+        user = self._data.get("states", {}).get(name, {})
+        default = STATE_DEFAULTS.get(name, {})
+        return {
+            "file": user.get("file") or default.get("file", f"backlog/{name}.md"),
+            "icon": user.get("icon") or default.get("icon", ""),
+        }
+
+    def state_path(self, name: str) -> Path:
+        """Absolute path for a state file."""
+        f = self.state(name)["file"]
+        p = Path(f)
+        # absolute path in config wins; relative resolves from root
+        return p if p.is_absolute() else self.root / p
+
+    def state_icon(self, name: str) -> str:
+        return self.state(name).get("icon", "")
+
+    # --- categories ---
+
+    @property
+    def categories(self) -> list[dict]:
+        return self._data.get("categories", [])
+
+    def category_names(self) -> list[str]:
+        return [c["name"] for c in self.categories]
+
+    def category_icon(self, name: str) -> str:
+        for cat in self.categories:
+            if cat["name"].lower() == name.lower():
+                return cat.get("icon", "")
+        return ""
+
+    def fuzzy_category(self, query: str) -> Optional[str]:
+        """
+        Case-insensitive substring match against category names and aliases.
+        Returns the canonical name if exactly one match, None otherwise.
+        Callers are responsible for surfacing ambiguity errors to the user.
+        """
+        q = query.strip().lower()
+        matches = [c["name"] for c in self.categories if q in c["name"].lower()]
+        if len(matches) == 1:
+            return matches[0]
+        # check aliases too — useful when migrating old category names
+        if not matches:
+            for cat in self.categories:
+                for alias in cat.get("aliases", []):
+                    if q in alias.lower():
+                        matches.append(cat["name"])
+        return matches[0] if len(matches) == 1 else None
+
+    def category_aliases(self) -> dict[str, str]:
+        """Flat alias → canonical name mapping for week-plan and reports."""
+        out: dict[str, str] = {}
+        for cat in self.categories:
+            name = cat["name"]
+            out[name] = name
+            for alias in cat.get("aliases", []):
+                out[alias] = name
+        return out
+
+    # --- phases ---
+
+    @property
+    def phases(self) -> list[dict]:
+        return self._data.get("phases", [])
+
+    # --- settings ---
+
+    @property
+    def repo_name(self) -> str:
+        return self._data.get("settings", {}).get("repo_name", "taskflow")
+
+    @property
+    def weekly_plan_dir(self) -> Path:
+        d = self._data.get("settings", {}).get("weekly_plan_dir", "changelog/weekly")
+        p = Path(d)
+        return p if p.is_absolute() else self.root / p
+
+    @property
+    def done_weeks(self) -> int:
+        """How many weeks to keep in done.md before archiving older ones."""
+        return int(self._data.get("settings", {}).get("done_weeks", 4))
+
+    @property
+    def archive_path(self) -> Path:
+        """Where archived week files live. Defaults next to the done file."""
+        default_archive = str(self.state_path("done").parent / "archive")
+        d = self._data.get("settings", {}).get("archive_path", default_archive)
+        p = Path(d)
+        return p if p.is_absolute() else self.root / p
+
+    # --- raw access for anything not covered above ---
+
+    def get(self, key: str, default=None):
+        return self._data.get(key, default)
+
+
+def find_root(start: Optional[Path] = None) -> Optional[Path]:
+    """
+    Walk up from start (default cwd) looking for .taskflow.yml.
+    Returns the directory containing it, or None if not found.
+    """
+    current = Path(start or os.getcwd()).resolve()
+    while True:
+        if (current / CONFIG_FILE).exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            # hit filesystem root
+            return None
+        current = parent
+
+
+def load_config(root: Optional[Path] = None) -> TaskflowConfig:
+    """
+    Load config from root, or discover root from cwd if not given.
+    Raises click.UsageError if no config found — callers get a clean error.
+    """
+    import click
+
+    if root is None:
+        root = find_root()
+    if root is None:
+        raise click.UsageError("No .taskflow.yml found. Run `taskflow init` to set up a project.")
+
+    config_path = root / CONFIG_FILE
+    try:
+        with config_path.open(encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    except Exception as e:
+        raise click.UsageError(f"Could not read {config_path}: {e}")
+
+    return TaskflowConfig(root, data)
+
+
+def load_config_or_none(root: Optional[Path] = None) -> Optional[TaskflowConfig]:
+    """Same as load_config but returns None instead of raising."""
+    try:
+        return load_config(root)
+    except Exception:
+        return None

taskflow/reports.py

@@ -0,0 +1,284 @@
+"""
+reports.py — pipeline and progress reports.
+
+Both reports read from the backlog files and produce either a terminal
+table or JSON. State file paths come from config so nothing here is
+hardcoded. Category ordering follows the config, extras are alphabetical,
+uncategorized is always last.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import defaultdict
+from datetime import date
+from pathlib import Path
+from typing import Optional
+
+from taskflow.config import TaskflowConfig
+from taskflow.tasklib import WEEK_HEADING_RE
+
+CATEGORY_RE = re.compile(r"^###\s+(?:[\U0001F300-\U0001FFFE\u2600-\u26FF\u2700-\u27BF]\s*)?(.*\S.*?)\s*$")
+PHASE_RE = re.compile(r"^##\s+(?!Week of)(.*\S.*?)\s*$")
+DIVIDER_RE = re.compile(r"^---\s*$")
+DONE_RE = re.compile(r"^\[[\d\s:\-]+\]\s+done:\s+\(([^)]+)\)\s+-\s+.+$")
+TASK_RE = re.compile(r"^\s*[*-]\s+\S")
+
+UNCATEGORIZED = "Uncategorized"
+
+
+def _strip_emoji(name: str) -> str:
+    return re.sub(r"^[\U0001F300-\U0001FFFE\u2600-\u26FF\u2700-\u27BF]\s*", "", name).strip()
+
+
+def count_tasks_by_category(path: Path) -> dict[str, int]:
+    """Count top-level (non-indented) tasks per category in a backlog file."""
+    if not path.exists():
+        return {}
+
+    counts: dict[str, int] = defaultdict(int)
+    current_cat: Optional[str] = None
+
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if PHASE_RE.match(line):
+            continue
+        m = CATEGORY_RE.match(line)
+        if m:
+            current_cat = _strip_emoji(m.group(1))
+            continue
+        if DIVIDER_RE.match(line):
+            current_cat = None
+            continue
+        # only count top-level tasks — subtasks start with whitespace
+        if TASK_RE.match(line) and not line.startswith("  "):
+            counts[current_cat or UNCATEGORIZED] += 1
+
+    return dict(counts)
+
+
+def parse_done_by_week(done_path: Path) -> list[tuple[str, dict[str, int]]]:
+    """
+    Parse done.md into (week_date_str, {category: count}) tuples, newest first.
+    Week date comes from the ## Week of YYYY-MM-DD heading.
+    """
+    if not done_path.exists():
+        return []
+
+    weeks: list[tuple[str, dict[str, int]]] = []
+    current_week: Optional[str] = None
+    current_counts: dict[str, int] = defaultdict(int)
+
+    for line in done_path.read_text(encoding="utf-8").splitlines():
+        m_week = WEEK_HEADING_RE.match(line)
+        if m_week:
+            if current_week is not None:
+                weeks.append((current_week, dict(current_counts)))
+            current_week = m_week.group(1)
+            current_counts = defaultdict(int)
+            continue
+
+        m_done = DONE_RE.match(line)
+        if m_done and current_week is not None:
+            cat = _strip_emoji(m_done.group(1).strip())
+            current_counts[cat] += 1
+
+    if current_week is not None:
+        weeks.append((current_week, dict(current_counts)))
+
+    # newest first
+    weeks.sort(key=lambda x: x[0], reverse=True)
+    return weeks
+
+
+def ordered_categories(
+    backlog_counts: dict[str, dict[str, int]],
+    week_counts: list[tuple[str, dict[str, int]]],
+    config: TaskflowConfig,
+) -> list[str]:
+    """
+    Category order: config order first, then alphabetical extras, uncategorized last.
+    """
+    seen: set[str] = set()
+    ordered: list[str] = []
+
+    # config order wins
+    for name in config.category_names():
+        if name not in seen:
+            ordered.append(name)
+            seen.add(name)
+
+    # anything in the files that isn't in config — alphabetical
+    extras: set[str] = set()
+    for counts in backlog_counts.values():
+        extras.update(c for c in counts if c != UNCATEGORIZED and c not in seen)
+    for _, counts in week_counts:
+        extras.update(c for c in counts if c != UNCATEGORIZED and c not in seen)
+    for name in sorted(extras):
+        ordered.append(name)
+        seen.add(name)
+
+    # uncategorized always last, only if present
+    has_unc = any(UNCATEGORIZED in counts for counts in list(backlog_counts.values()) + [c for _, c in week_counts])
+    if has_unc:
+        ordered.append(UNCATEGORIZED)
+
+    return ordered
+
+
+# ---------------------------------------------------------------------------
+# Table renderer
+# ---------------------------------------------------------------------------
+
+
+def _pad(s: str, width: int, align: str = "left") -> str:
+    s = str(s)
+    return s.rjust(width) if align == "right" else s.ljust(width)
+
+
+def render_table(headers: list[str], rows: list[list[str]], col_aligns: Optional[list[str]] = None) -> str:
+    n = len(headers)
+    col_aligns = col_aligns or ["left"] * n
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            if i < n:
+                widths[i] = max(widths[i], len(str(cell)))
+
+    sep = "+" + "+".join("-" * (w + 2) for w in widths) + "+"
+    hdr = "|" + "|".join(f" {_pad(h, widths[i])} " for i, h in enumerate(headers)) + "|"
+
+    lines = [sep, hdr, sep]
+    for row in rows:
+        cells = []
+        for i in range(n):
+            val = row[i] if i < len(row) else ""
+            cells.append(f" {_pad(val, widths[i], col_aligns[i] if i < len(col_aligns) else 'left')} ")
+        lines.append("|" + "|".join(cells) + "|")
+    lines.append(sep)
+    return "\n".join(lines)
+
+
+def _fmt_week(d: str) -> str:
+    try:
+        dt = date.fromisoformat(d)
+        return dt.strftime("%b %-d")
+    except Exception:
+        return d
+
+
+def _cat_label(name: str, config: TaskflowConfig) -> str:
+    icon = config.category_icon(name)
+    return f"{icon} {name}".strip() if icon else name
+
+
+# ---------------------------------------------------------------------------
+# progress report
+# ---------------------------------------------------------------------------
+
+
+def report_progress(config: TaskflowConfig, as_json: bool = False, max_weeks: int = 5) -> str:
+    now_counts = count_tasks_by_category(config.state_path("now"))
+    done_by_week = parse_done_by_week(config.state_path("done"))
+    weeks = done_by_week[:max_weeks]
+    categories = ordered_categories({"now": now_counts}, weeks, config)
+
+    if as_json:
+        data = {
+            "report": "progress",
+            "columns": ["now"] + [w for w, _ in weeks],
+            "rows": [],
+        }
+        for cat in categories:
+            row: dict = {"category": cat, "now": now_counts.get(cat, 0)}
+            for wd, counts in weeks:
+                row[wd] = counts.get(cat, 0)
+            data["rows"].append(row)
+        return json.dumps(data, indent=2)
+
+    now_icon = config.state_icon("now")
+    done_icon = config.state_icon("done")
+
+    headers = ["Category", f"{now_icon} Now".strip()] + [f"{done_icon} {_fmt_week(w)}".strip() for w, _ in weeks]
+    col_aligns = ["left"] + ["right"] * (1 + len(weeks))
+    rows = [[_cat_label(cat, config), str(now_counts.get(cat, 0))] + [str(c.get(cat, 0)) for _, c in weeks] for cat in categories]
+    return f"\n  progress — now vs. completed by week\n\n{render_table(headers, rows, col_aligns)}\n"
+
+
+# ---------------------------------------------------------------------------
+# pipeline report
+# ---------------------------------------------------------------------------
+
+
+def report_pipeline(config: TaskflowConfig, as_json: bool = False) -> str:
+    later_counts = count_tasks_by_category(config.state_path("later"))
+    next_counts = count_tasks_by_category(config.state_path("next"))
+    paused_counts = count_tasks_by_category(config.state_path("paused"))
+    blocked_counts = count_tasks_by_category(config.state_path("blocked"))
+    now_counts = count_tasks_by_category(config.state_path("now"))
+    done_by_week = parse_done_by_week(config.state_path("done"))
+
+    this_week_counts = done_by_week[0][1] if done_by_week else {}
+    this_week_date = done_by_week[0][0] if done_by_week else None
+
+    all_counts = {
+        "later": later_counts,
+        "next": next_counts,
+        "paused": paused_counts,
+        "blocked": blocked_counts,
+        "now": now_counts,
+        "this_week": this_week_counts,
+    }
+    categories = ordered_categories(all_counts, [], config)
+
+    if as_json:
+        return json.dumps(
+            {
+                "report": "pipeline",
+                "columns": ["later", "next", "paused", "blocked", "now", "this_week"],
+                "this_week_heading": this_week_date,
+                "rows": [
+                    {
+                        "category": cat,
+                        "later": later_counts.get(cat, 0),
+                        "next": next_counts.get(cat, 0),
+                        "paused": paused_counts.get(cat, 0),
+                        "blocked": blocked_counts.get(cat, 0),
+                        "now": now_counts.get(cat, 0),
+                        "this_week": this_week_counts.get(cat, 0),
+                    }
+                    for cat in categories
+                ],
+            },
+            indent=2,
+        )
+
+    def si(key: str, fallback: str) -> str:
+        return config.state_icon(key) or fallback
+
+    week_label = f"{si('done', '✓')} {_fmt_week(this_week_date)}".strip() if this_week_date else "This Week"
+
+    headers = [
+        "Category",
+        f"{si('later', '◇')} Later".strip(),
+        f"{si('next', '◈')} Next".strip(),
+        f"{si('paused', '⏸')} Paused".strip(),
+        f"{si('blocked', '⊘')} Blocked".strip(),
+        f"{si('now', '▶')} Now".strip(),
+        week_label,
+    ]
+    col_aligns = ["left"] + ["right"] * 6
+    rows = [
+        [
+            _cat_label(cat, config),
+            str(later_counts.get(cat, 0)),
+            str(next_counts.get(cat, 0)),
+            str(paused_counts.get(cat, 0)),
+            str(blocked_counts.get(cat, 0)),
+            str(now_counts.get(cat, 0)),
+            str(this_week_counts.get(cat, 0)),
+        ]
+        for cat in categories
+    ]
+
+    return f"\n  pipeline — work in flight and completed this week\n\n{render_table(headers, rows, col_aligns)}\n"