kaiten-cli 0.3.3__py3-none-any.whl

kaiten_cli/runtime/snapshot_common.py

@@ -0,0 +1,363 @@
+"""Shared snapshot constants and pure transformation helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from kaiten_cli.errors import ValidationError
+from kaiten_cli.i18n import tr
+from kaiten_cli.runtime.transforms import compact_response, select_fields, strip_base64
+
+SNAPSHOT_PRESETS = {"basic", "analytics", "evidence", "full"}
+WINDOW_PRESETS = {"analytics", "full"}
+QUERY_METRICS = {"count", "wip", "throughput", "lead_time", "cycle_time", "aging"}
+QUERY_GROUP_BY = {
+    "board_id",
+    "column_id",
+    "lane_id",
+    "type_id",
+    "owner_id",
+    "responsible_id",
+    "state",
+    "condition",
+}
+QUERY_FILTER_KEYS = {
+    "board_ids",
+    "column_ids",
+    "lane_ids",
+    "type_ids",
+    "tag_ids",
+    "owner_ids",
+    "responsible_ids",
+    "states",
+    "condition",
+    "created_after",
+    "created_before",
+    "updated_after",
+    "updated_before",
+    "has_children",
+    "has_comments",
+    "text_query",
+    "child_text_query",
+    "comment_text_query",
+}
+DEFAULT_LOCAL_LIMIT = 100
+SNAPSHOT_SCHEMA_VERSION = 2
+SNAPSHOT_DB_SCHEMA_VERSION = 1
+QUERY_CARD_VIEWS = {"summary", "detail", "evidence"}
+
+SUMMARY_VIEW_FIELDS = (
+    "id",
+    "title",
+    "board_id",
+    "column_id",
+    "lane_id",
+    "type_id",
+    "owner_id",
+    "responsible_id",
+    "state",
+    "condition",
+    "created",
+    "updated",
+    "has_children",
+    "has_comments",
+    "children_count",
+    "comments_count",
+    "time_spent_total_minutes",
+    "last_time_log_at",
+    "current_stage_entered_at",
+    "done_at",
+    "age_days",
+    "lead_time_days",
+    "cycle_time_days",
+)
+DETAIL_VIEW_FIELDS = SUMMARY_VIEW_FIELDS + (
+    "description",
+    "tag_ids",
+    "latest_stage",
+    "latest_column_id",
+    "latest_lane_id",
+    "work_started_at",
+    "commitment_at",
+)
+EVIDENCE_VIEW_FIELDS = DETAIL_VIEW_FIELDS + (
+    "search_text",
+    "child_text",
+    "comment_text",
+)
+VIEW_FIELDS = {
+    "summary": SUMMARY_VIEW_FIELDS,
+    "detail": DETAIL_VIEW_FIELDS,
+    "evidence": EVIDENCE_VIEW_FIELDS,
+}
+
+
+def _parse_timestamp(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        return parsed.astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def _iso_timestamp(value: datetime | None) -> str | None:
+    if value is None:
+        return None
+    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _now_iso() -> str:
+    return _iso_timestamp(datetime.now(timezone.utc)) or ""
+
+
+def _stats_snapshot(stats) -> dict[str, int]:
+    return {
+        "http_request_count": stats.http_request_count,
+        "http_response_count": stats.http_response_count,
+        "http_error_count": stats.http_error_count,
+        "api_wait_ms": stats.api_wait_ms,
+        "http_wait_ms": stats.http_wait_ms,
+        "retry_count": stats.retry_count,
+        "request_cache_hits": stats.request_cache_hits,
+        "request_cache_misses": stats.request_cache_misses,
+        "inflight_dedup_hits": stats.inflight_dedup_hits,
+        "disk_cache_hits": stats.disk_cache_hits,
+        "disk_cache_misses": stats.disk_cache_misses,
+        "disk_cache_expired": stats.disk_cache_expired,
+        "disk_cache_bypasses": stats.disk_cache_bypasses,
+    }
+
+
+def _stats_delta(after: dict[str, Any], before: dict[str, Any]) -> dict[str, Any]:
+    return {key: after[key] - before.get(key, 0) for key in after}
+
+
+def _duration_stats(values: list[float]) -> dict[str, Any] | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+
+    def percentile(percent: float) -> float:
+        if len(ordered) == 1:
+            return ordered[0]
+        rank = (len(ordered) - 1) * percent
+        lower = int(rank)
+        upper = min(lower + 1, len(ordered) - 1)
+        fraction = rank - lower
+        return ordered[lower] + (ordered[upper] - ordered[lower]) * fraction
+
+    return {
+        "count": len(ordered),
+        "median_days": round(percentile(0.5), 2),
+        "p85_days": round(percentile(0.85), 2),
+        "max_days": round(ordered[-1], 2),
+    }
+
+
+def _normalize_int_list(value: Any) -> list[int]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        raw_items = value
+    elif isinstance(value, str):
+        raw_items = [item.strip() for item in value.split(",") if item.strip()]
+    else:
+        raw_items = [value]
+    normalized: list[int] = []
+    for item in raw_items:
+        try:
+            normalized.append(int(item))
+        except (TypeError, ValueError) as exc:
+            raise ValidationError(
+                tr("Invalid integer list value: {value_0}", value_0=item)
+            ) from exc
+    return normalized
+
+
+def _normalize_string(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip().lower()
+
+
+def _normalize_bool(value: Any) -> bool | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    raise ValidationError(tr("Boolean filters must use true or false."))
+
+
+def _extract_id(value: Any) -> int | None:
+    if isinstance(value, int):
+        return value
+    if isinstance(value, dict):
+        nested = value.get("id")
+        if isinstance(nested, int):
+            return nested
+    return None
+
+
+def _extract_tag_ids(card: dict[str, Any]) -> list[int]:
+    tags = card.get("tags")
+    if not isinstance(tags, list):
+        return []
+    tag_ids: list[int] = []
+    for tag in tags:
+        tag_id = _extract_id(tag)
+        if tag_id is not None:
+            tag_ids.append(tag_id)
+    return tag_ids
+
+
+def _time_log_minutes(entry: dict[str, Any]) -> int:
+    for key in ("time_spent", "timeSpent", "minutes"):
+        value = entry.get(key)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.strip():
+            try:
+                return int(value)
+            except ValueError:
+                continue
+    return 0
+
+
+def _time_log_timestamp(entry: dict[str, Any]) -> datetime | None:
+    for key in ("created", "updated", "for_date", "forDate", "date"):
+        changed = _parse_timestamp(entry.get(key))
+        if changed is not None:
+            return changed
+    return None
+
+
+def _search_blob(parts: list[str]) -> str:
+    normalized = [part.strip() for part in parts if part and str(part).strip()]
+    return "\n".join(normalized)
+
+
+def _duration_days(start: datetime | None, end: datetime | None) -> float | None:
+    if start is None or end is None or start > end:
+        return None
+    return round((end - start).total_seconds() / 86400, 2)
+
+
+def _effective_column_id(event: dict[str, Any]) -> int | None:
+    for key in ("subcolumn_id", "column_id"):
+        value = event.get(key)
+        if isinstance(value, int):
+            return value
+    return None
+
+
+def _sorted_history(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return sorted(
+        [row for row in rows if isinstance(row, dict)],
+        key=lambda row: (
+            str(row.get("changed", "")),
+            int(row.get("column_id") or 0),
+            int(row.get("lane_id") or 0),
+        ),
+    )
+
+
+def _first_history_with_state(history: list[dict[str, Any]], state: int) -> datetime | None:
+    for row in history:
+        if row.get("state") == state:
+            return _parse_timestamp(row.get("changed"))
+    return None
+
+
+def _derive_done_at(card: dict[str, Any], history: list[dict[str, Any]]) -> datetime | None:
+    card_done = _parse_timestamp(card.get("last_moved_to_done_at"))
+    if card_done is not None:
+        return card_done
+    latest_done: datetime | None = None
+    for row in history:
+        changed = _parse_timestamp(row.get("changed"))
+        if changed is None:
+            continue
+        if row.get("state") == 3:
+            latest_done = changed
+    return latest_done
+
+
+def _current_stage_entered_at(history: list[dict[str, Any]]) -> datetime | None:
+    if not history:
+        return None
+    latest = history[-1]
+    latest_column = _effective_column_id(latest)
+    latest_lane = latest.get("lane_id")
+    latest_condition = latest.get("condition")
+    latest_state = latest.get("state")
+    for row in reversed(history):
+        if (
+            _effective_column_id(row) != latest_column
+            or row.get("lane_id") != latest_lane
+            or row.get("condition") != latest_condition
+            or row.get("state") != latest_state
+        ):
+            break
+        changed = _parse_timestamp(row.get("changed"))
+        if changed is not None:
+            return changed
+    return _parse_timestamp(latest.get("changed"))
+
+
+def _within_window(
+    changed: datetime | None, window_start: datetime | None, window_end: datetime | None
+) -> bool:
+    if changed is None:
+        return False
+    if window_start is not None and changed < window_start:
+        return False
+    if window_end is not None and changed > window_end:
+        return False
+    return True
+
+
+def _filter_time_logs_to_window(
+    time_logs: list[dict[str, Any]],
+    *,
+    window_start: datetime | None,
+    window_end: datetime | None,
+) -> list[dict[str, Any]]:
+    if window_start is None and window_end is None:
+        return [row for row in time_logs if isinstance(row, dict)]
+    return [
+        row
+        for row in time_logs
+        if isinstance(row, dict)
+        and _within_window(_time_log_timestamp(row), window_start, window_end)
+    ]
+
+
+def _view_fields(view: str, fields: str | None) -> str | None:
+    if fields:
+        return fields
+    return ",".join(VIEW_FIELDS[view])
+
+
+def _shape_card_for_output(
+    record: dict[str, Any],
+    *,
+    view: str,
+    compact: bool,
+    fields: str | None,
+) -> dict[str, Any]:
+    payload = dict(record["card"])
+    payload.update(record["derived"])
+    view_field_names = VIEW_FIELDS[view]
+    payload = {field: payload[field] for field in view_field_names if field in payload}
+    shaped = compact_response(payload, compact)
+    shaped = select_fields(shaped, _view_fields(view, fields))
+    shaped, _ = strip_base64(shaped)
+    return shaped

kaiten_cli/runtime/snapshot_query.py

@@ -0,0 +1,306 @@
+"""Local-only snapshot card queries and generic metric aggregation."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Any
+
+from kaiten_cli.errors import ValidationError
+from kaiten_cli.i18n import tr
+from kaiten_cli.runtime.snapshot_common import (
+    DEFAULT_LOCAL_LIMIT,
+    QUERY_FILTER_KEYS,
+    _duration_stats,
+    _iso_timestamp,
+    _normalize_bool,
+    _normalize_int_list,
+    _normalize_string,
+    _parse_timestamp,
+    _shape_card_for_output,
+)
+from kaiten_cli.runtime.snapshot_store import SnapshotStore
+
+
+def validate_query_filter(tool, payload: dict[str, Any]) -> None:
+    filter_payload = payload.get("filter")
+    if filter_payload is None:
+        return
+    if not isinstance(filter_payload, dict):
+        raise ValidationError(tr("Field filter must be an object."))
+    unknown = sorted(set(filter_payload) - QUERY_FILTER_KEYS)
+    if unknown:
+        raise ValidationError(
+            tr("Unknown query filter field(s): {value_0}", value_0=", ".join(unknown))
+        )
+
+
+def _matches_query_filter(record: dict[str, Any], filters: dict[str, Any]) -> bool:
+    board_ids = _normalize_int_list(filters.get("board_ids"))
+    if board_ids and record["board_id"] not in board_ids:
+        return False
+    column_ids = _normalize_int_list(filters.get("column_ids"))
+    if column_ids and record["column_id"] not in column_ids:
+        return False
+    lane_ids = _normalize_int_list(filters.get("lane_ids"))
+    if lane_ids and record["lane_id"] not in lane_ids:
+        return False
+    type_ids = _normalize_int_list(filters.get("type_ids"))
+    if type_ids and record["type_id"] not in type_ids:
+        return False
+    owner_ids = _normalize_int_list(filters.get("owner_ids"))
+    if owner_ids and record["owner_id"] not in owner_ids:
+        return False
+    responsible_ids = _normalize_int_list(filters.get("responsible_ids"))
+    if responsible_ids and record["responsible_id"] not in responsible_ids:
+        return False
+    states = _normalize_int_list(filters.get("states"))
+    if states and record["state"] not in states:
+        return False
+    condition_values = _normalize_int_list(filters.get("condition"))
+    if condition_values and record["condition"] not in condition_values:
+        return False
+    tag_ids = _normalize_int_list(filters.get("tag_ids"))
+    if tag_ids and not (set(record["tag_ids"]) & set(tag_ids)):
+        return False
+
+    created = _parse_timestamp(record["created"])
+    updated = _parse_timestamp(record["updated"])
+    created_after = _parse_timestamp(filters.get("created_after"))
+    if created_after is not None and (created is None or created < created_after):
+        return False
+    created_before = _parse_timestamp(filters.get("created_before"))
+    if created_before is not None and (created is None or created > created_before):
+        return False
+    updated_after = _parse_timestamp(filters.get("updated_after"))
+    if updated_after is not None and (updated is None or updated < updated_after):
+        return False
+    updated_before = _parse_timestamp(filters.get("updated_before"))
+    if updated_before is not None and (updated is None or updated > updated_before):
+        return False
+
+    has_children = _normalize_bool(filters.get("has_children"))
+    if has_children is not None and record["has_children"] != has_children:
+        return False
+    has_comments = _normalize_bool(filters.get("has_comments"))
+    if has_comments is not None and record["has_comments"] != has_comments:
+        return False
+
+    text_query = _normalize_string(filters.get("text_query"))
+    if text_query and text_query not in record["search_text"].lower():
+        return False
+    child_text_query = _normalize_string(filters.get("child_text_query"))
+    if child_text_query and child_text_query not in record["child_text"].lower():
+        return False
+    comment_text_query = _normalize_string(filters.get("comment_text_query"))
+    if comment_text_query and comment_text_query not in record["comment_text"].lower():
+        return False
+    return True
+
+
+def _text_candidate_ids(
+    store: SnapshotStore, snapshot_name: str, filters: dict[str, Any]
+) -> set[int] | None:
+    candidate_sets: list[set[int]] = []
+    mapping = {
+        "text_query": "search_text",
+        "child_text_query": "child_text",
+        "comment_text_query": "comment_text",
+    }
+    for filter_name, column_name in mapping.items():
+        query = _normalize_string(filters.get(filter_name))
+        if query:
+            candidate_sets.append(store.text_candidate_card_ids(snapshot_name, column_name, query))
+    if not candidate_sets:
+        return None
+    candidates = candidate_sets[0]
+    for subset in candidate_sets[1:]:
+        candidates &= subset
+    return candidates
+
+
+async def execute_query_cards(
+    client,
+    tool,
+    payload: dict[str, Any],
+    path: str,
+    query: dict[str, Any] | None,
+    body: dict[str, Any] | None,
+    timeout: float,
+    reporter,
+) -> Any:
+    store = SnapshotStore(reporter=reporter)
+    snapshot = store.get_snapshot(payload["snapshot"])
+    filters = payload.get("filter") or {}
+    candidate_ids = _text_candidate_ids(store, payload["snapshot"], filters)
+    offset = max(int(payload.get("offset", 0)), 0)
+    limit = max(int(payload.get("limit", DEFAULT_LOCAL_LIMIT)), 1)
+    view = payload.get("view", "summary")
+    sliced, total = store.query_card_records(
+        payload["snapshot"],
+        filters,
+        candidate_ids,
+        limit=limit,
+        offset=offset,
+    )
+    items = [
+        _shape_card_for_output(
+            record,
+            view=view,
+            compact=bool(payload.get("compact", False)),
+            fields=payload.get("fields"),
+        )
+        for record in sliced
+    ]
+    return {
+        "snapshot": snapshot["name"],
+        "items": items,
+        "meta": {
+            "view": view,
+            "total": total,
+            "returned": len(items),
+            "offset": offset,
+            "limit": limit,
+            "window": snapshot["window"],
+        },
+    }
+
+
+def _group_label(record: dict[str, Any], group_by: str | None) -> str:
+    if not group_by:
+        return "all"
+    value = record.get(group_by)
+    return "null" if value is None else str(value)
+
+
+def _metric_cutoff(snapshot: dict[str, Any]) -> datetime:
+    cutoff = _parse_timestamp(snapshot["window"].get("end"))
+    if cutoff is not None:
+        return cutoff
+    built_at = _parse_timestamp(snapshot["built_at"])
+    return built_at or datetime.now(timezone.utc)
+
+
+def _metric_done_in_window(done_at: datetime | None, snapshot: dict[str, Any]) -> bool:
+    if done_at is None:
+        return False
+    start = _parse_timestamp(snapshot["window"].get("start"))
+    end = _parse_timestamp(snapshot["window"].get("end"))
+    if start is not None and done_at < start:
+        return False
+    if end is not None and done_at > end:
+        return False
+    return True
+
+
+async def execute_query_metrics(
+    client,
+    tool,
+    payload: dict[str, Any],
+    path: str,
+    query: dict[str, Any] | None,
+    body: dict[str, Any] | None,
+    timeout: float,
+    reporter,
+) -> Any:
+    store = SnapshotStore(reporter=reporter)
+    snapshot = store.get_snapshot(payload["snapshot"])
+    filters = payload.get("filter") or {}
+    candidate_ids = _text_candidate_ids(store, payload["snapshot"], filters)
+    metric = payload["metric"]
+    group_by = payload.get("group_by")
+    cutoff = _metric_cutoff(snapshot)
+    metric_column_map = {
+        "count": ("card_id", group_by or "card_id"),
+        "wip": ("card_id", group_by or "card_id", "condition", "state"),
+        "throughput": ("card_id", group_by or "card_id", "done_at"),
+        "lead_time": ("card_id", group_by or "card_id", "lead_time_days", "done_at"),
+        "cycle_time": ("card_id", group_by or "card_id", "cycle_time_days", "done_at"),
+        "aging": ("card_id", group_by or "card_id", "age_days", "condition", "state"),
+    }
+    metric_columns = tuple(dict.fromkeys(metric_column_map[metric]))
+    rows_source = store.load_metric_rows(
+        payload["snapshot"], filters, candidate_ids, metric_columns
+    )
+    grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    matched_cards = 0
+    for row in rows_source:
+        matched_cards += 1
+        row_payload = dict(row)
+        grouped[_group_label(row_payload, group_by)].append(row_payload)
+
+    rows: list[dict[str, Any]] = []
+    for group_value, group_records in sorted(grouped.items()):
+        if metric == "count":
+            rows.append({"group": group_value, "value": len(group_records)})
+            continue
+        if metric == "wip":
+            count = sum(
+                1 for record in group_records if record["condition"] == 1 and record["state"] != 3
+            )
+            rows.append({"group": group_value, "value": count, "as_of": _iso_timestamp(cutoff)})
+            continue
+        if metric == "throughput":
+            count = 0
+            for record in group_records:
+                if _metric_done_in_window(_parse_timestamp(record["done_at"]), snapshot):
+                    count += 1
+            rows.append({"group": group_value, "value": count, "window": snapshot["window"]})
+            continue
+        if metric == "lead_time":
+            durations = []
+            for record in group_records:
+                done_at = _parse_timestamp(record["done_at"])
+                duration = record.get("lead_time_days")
+                if (
+                    done_at is None
+                    or duration is None
+                    or not _metric_done_in_window(done_at, snapshot)
+                ):
+                    continue
+                durations.append(float(duration))
+            rows.append({"group": group_value, "stats": _duration_stats(durations)})
+            continue
+        if metric == "cycle_time":
+            durations = []
+            for record in group_records:
+                done_at = _parse_timestamp(record["done_at"])
+                duration = record.get("cycle_time_days")
+                if (
+                    done_at is None
+                    or duration is None
+                    or not _metric_done_in_window(done_at, snapshot)
+                ):
+                    continue
+                durations.append(float(duration))
+            rows.append({"group": group_value, "stats": _duration_stats(durations)})
+            continue
+        if metric == "aging":
+            ages = []
+            for record in group_records:
+                if record["condition"] != 1 or record["state"] == 3:
+                    continue
+                age_days = record.get("age_days")
+                if age_days is None:
+                    continue
+                ages.append(float(age_days))
+            rows.append(
+                {
+                    "group": group_value,
+                    "stats": _duration_stats(ages),
+                    "as_of": _iso_timestamp(cutoff),
+                }
+            )
+            continue
+
+    return {
+        "snapshot": snapshot["name"],
+        "metric": metric,
+        "group_by": group_by,
+        "rows": rows,
+        "meta": {
+            "matched_cards": matched_cards,
+            "window": snapshot["window"],
+            "built_at": snapshot["built_at"],
+        },
+    }