@grifhinz/logics-manager 2.1.1 → 2.2.0

package/logics_manager/index.py

@@ -8,6 +8,7 @@ from os import path as os_path
 from pathlib import Path
 
 from .config import find_repo_root
+from .path_utils import resolve_repo_output_path
 
 
 @dataclass(frozen=True)
@@ -91,7 +92,7 @@ def index_payload(repo_root: Path, *, out: str = "logics/INDEX.md") -> dict[str,
     for title, rel_dir, show_progress in SECTION_DEFINITIONS:
         sections.append((title, _collect_entries(repo_root, rel_dir), show_progress))
 
-    out_path = (repo_root / out).resolve()
+    out_path, output_path = resolve_repo_output_path(repo_root, out)
     out_dir = out_path.parent
     content = "\n".join(
         [
@@ -104,15 +105,10 @@ def index_payload(repo_root: Path, *, out: str = "logics/INDEX.md") -> dict[str,
     out_path.parent.mkdir(parents=True, exist_ok=True)
     out_path.write_text(content, encoding="utf-8")
 
-    try:
-        printable = out_path.relative_to(repo_root)
-    except ValueError:
-        printable = out_path
-
     counts = {key: len(entries) for key, (_, entries, _) in zip(SECTION_COUNT_KEYS, sections)}
     return {
         "ok": True,
-        "output_path": printable.as_posix(),
+        "output_path": output_path,
         "counts": counts,
     }
 

package/logics_manager/insights.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+
+WORKFLOW_KINDS = ("request", "backlog", "task")
+COMPANION_KINDS = ("product", "architecture")
+OPEN_STATUSES = {"Draft", "Ready", "In progress", "Blocked"}
+CLOSED_STATUSES = {"Done", "Archived"}
+
+
+@dataclass(frozen=True)
+class LogicsDoc:
+    kind: str
+    path: Path
+    rel_path: str
+    ref: str
+    title: str
+    status: str | None
+    progress: int | None
+    content: str
+
+
+def _doc_dirs(repo_root: Path) -> dict[str, Path]:
+    return {
+        "request": repo_root / "logics" / "request",
+        "backlog": repo_root / "logics" / "backlog",
+        "task": repo_root / "logics" / "tasks",
+        "product": repo_root / "logics" / "product",
+        "architecture": repo_root / "logics" / "architecture",
+    }
+
+
+def _progress_value(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    match = re.search(r"(\d+)", raw)
+    if not match:
+        return None
+    return max(0, min(100, int(match.group(1))))
+
+
+def _parse_doc(repo_root: Path, kind: str, path: Path) -> LogicsDoc:
+    content = path.read_text(encoding="utf-8")
+    title = "(missing title)"
+    status: str | None = None
+    progress: int | None = None
+    for line in content.splitlines():
+        if line.startswith("## "):
+            heading = line.removeprefix("## ").strip()
+            if " - " in heading:
+                _, title = heading.split(" - ", 1)
+            else:
+                title = heading
+            continue
+        if line.startswith("> Status:"):
+            status = line.split(":", 1)[1].strip()
+            continue
+        if line.startswith("> Progress:"):
+            progress = _progress_value(line.split(":", 1)[1].strip())
+            continue
+    return LogicsDoc(
+        kind=kind,
+        path=path,
+        rel_path=path.relative_to(repo_root).as_posix(),
+        ref=path.stem,
+        title=title,
+        status=status,
+        progress=progress,
+        content=content,
+    )
+
+
+def collect_logics_docs(repo_root: Path, *, kinds: tuple[str, ...] = WORKFLOW_KINDS + COMPANION_KINDS) -> list[LogicsDoc]:
+    docs: list[LogicsDoc] = []
+    for kind, directory in _doc_dirs(repo_root).items():
+        if kind not in kinds or not directory.is_dir():
+            continue
+        for path in sorted(directory.glob("*.md")):
+            docs.append(_parse_doc(repo_root, kind, path))
+    return docs
+
+
+def _status_counts(docs: list[LogicsDoc]) -> dict[str, dict[str, int]]:
+    counts: dict[str, dict[str, int]] = {}
+    for doc in docs:
+        status = doc.status or "(missing)"
+        counts.setdefault(doc.kind, {})
+        counts[doc.kind][status] = counts[doc.kind].get(status, 0) + 1
+    return counts
+
+
+def _doc_summary(doc: LogicsDoc) -> dict[str, object]:
+    return {
+        "ref": doc.ref,
+        "title": doc.title,
+        "kind": doc.kind,
+        "status": doc.status,
+        "progress": doc.progress,
+        "path": doc.rel_path,
+    }
+
+
+def status_payload(repo_root: Path, *, limit: int = 10) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS)
+    open_docs = [doc for doc in docs if doc.status not in CLOSED_STATUSES]
+    active_tasks = [
+        doc
+        for doc in open_docs
+        if doc.kind == "task" and doc.status in {"Ready", "In progress", "Blocked"}
+    ]
+    ready_backlog = [
+        doc
+        for doc in open_docs
+        if doc.kind == "backlog" and doc.status in {"Ready", "In progress", "Blocked"}
+    ]
+    task_text = "\n".join(doc.content for doc in docs if doc.kind == "task")
+    backlog_without_task = [doc for doc in ready_backlog if doc.ref not in task_text]
+    draft_requests = [doc for doc in open_docs if doc.kind == "request" and doc.status == "Draft"]
+    blocked_docs = [doc for doc in open_docs if doc.status == "Blocked"]
+
+    next_actions: list[str] = []
+    if blocked_docs:
+        next_actions.append(f"Review {len(blocked_docs)} blocked doc(s).")
+    if active_tasks:
+        next_actions.append(f"Continue or finish {len(active_tasks)} active task(s).")
+    if backlog_without_task:
+        next_actions.append(f"Promote {len(backlog_without_task)} ready backlog item(s) without detected task links.")
+    if draft_requests:
+        next_actions.append(f"Groom {len(draft_requests)} draft request(s).")
+    if not next_actions:
+        next_actions.append("No open workflow action detected.")
+
+    return {
+        "ok": True,
+        "counts": _status_counts(docs),
+        "open_count": len(open_docs),
+        "active_tasks": [_doc_summary(doc) for doc in active_tasks[:limit]],
+        "backlog_without_task": [_doc_summary(doc) for doc in backlog_without_task[:limit]],
+        "draft_requests": [_doc_summary(doc) for doc in draft_requests[:limit]],
+        "blocked_docs": [_doc_summary(doc) for doc in blocked_docs[:limit]],
+        "next_actions": next_actions,
+    }
+
+
+def render_status(repo_root: Path, *, output_format: str = "text", limit: int = 10) -> str:
+    payload = status_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Logics status:",
+        f"- open workflow docs: {payload['open_count']}",
+        "- next actions:",
+    ]
+    lines.extend(f"  - {action}" for action in payload["next_actions"])
+    for key, label in (
+        ("active_tasks", "Active tasks"),
+        ("backlog_without_task", "Backlog without detected task"),
+        ("draft_requests", "Draft requests"),
+        ("blocked_docs", "Blocked docs"),
+    ):
+        items = payload[key]
+        if not items:
+            continue
+        lines.append(f"- {label}:")
+        for item in items:
+            lines.append(f"  - {item['ref']} [{item['status']}]: {item['title']}")
+    return "\n".join(lines)
+
+
+def health_payload(repo_root: Path, *, limit: int = 10) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    workflow_docs = [doc for doc in docs if doc.kind in WORKFLOW_KINDS]
+    missing_status = [doc for doc in docs if not doc.status]
+    done_without_full_progress = [
+        doc for doc in workflow_docs if doc.status == "Done" and doc.kind in {"backlog", "task"} and doc.progress != 100
+    ]
+    complete_progress_not_done = [
+        doc for doc in workflow_docs if doc.progress == 100 and doc.status not in CLOSED_STATUSES
+    ]
+    blocked_docs = [doc for doc in workflow_docs if doc.status == "Blocked"]
+    open_docs = [doc for doc in workflow_docs if doc.status not in CLOSED_STATUSES]
+
+    task_text = "\n".join(doc.content for doc in workflow_docs if doc.kind == "task")
+    backlog_without_task = [
+        doc
+        for doc in open_docs
+        if doc.kind == "backlog" and doc.status in {"Ready", "In progress", "Blocked"} and doc.ref not in task_text
+    ]
+
+    issue_groups = {
+        "missing_status": missing_status,
+        "done_without_full_progress": done_without_full_progress,
+        "complete_progress_not_done": complete_progress_not_done,
+        "blocked_docs": blocked_docs,
+        "backlog_without_task": backlog_without_task,
+    }
+    issue_count = sum(len(items) for items in issue_groups.values())
+    return {
+        "ok": issue_count == 0,
+        "doc_count": len(docs),
+        "workflow_doc_count": len(workflow_docs),
+        "open_workflow_count": len(open_docs),
+        "counts": _status_counts(docs),
+        "issue_count": issue_count,
+        "issues": {key: [_doc_summary(doc) for doc in items[:limit]] for key, items in issue_groups.items()},
+    }
+
+
+def render_health(repo_root: Path, *, output_format: str = "text", limit: int = 10) -> str:
+    payload = health_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Logics health:",
+        f"- docs: {payload['doc_count']}",
+        f"- workflow docs: {payload['workflow_doc_count']}",
+        f"- open workflow docs: {payload['open_workflow_count']}",
+        f"- issue signals: {payload['issue_count']}",
+    ]
+    issues = payload["issues"]
+    for key, items in issues.items():
+        if not items:
+            continue
+        label = key.replace("_", " ")
+        lines.append(f"- {label}:")
+        for item in items:
+            lines.append(f"  - {item['ref']} [{item['status']}]: {item['title']}")
+    return "\n".join(lines)
+
+
+def _slug_command_title(text: str) -> str:
+    cleaned = re.sub(r"`([^`]+)`", r"\1", text)
+    cleaned = re.sub(r"[*_]+", "", cleaned)
+    cleaned = re.sub(r"\s+", " ", cleaned.strip(" .:-"))
+    if len(cleaned) > 96:
+        cleaned = cleaned[:93].rstrip(" ,.;:") + "..."
+    return cleaned[:1].upper() + cleaned[1:] if cleaned else "Follow up"
+
+
+def _is_actionable_followup(text: str) -> bool:
+    normalized = re.sub(r"\s+", " ", text.strip(" .")).lower()
+    if normalized in {"none", "n/a", "not needed", "no follow-up"}:
+        return False
+    if normalized.startswith("no ") and "follow-up" in normalized:
+        return False
+    if normalized.startswith("no ") and "is required" in normalized:
+        return False
+    if "no new adr is required" in normalized:
+        return False
+    if "no new architecture decision" in normalized:
+        return False
+    return True
+
+
+def followups_payload(
+    repo_root: Path,
+    *,
+    limit: int = 50,
+    source_kind: str = "all",
+    include_closed: bool = False,
+    closed_only: bool = False,
+) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    if source_kind != "all":
+        docs = [doc for doc in docs if doc.kind == source_kind]
+    if closed_only:
+        docs = [doc for doc in docs if doc.status in CLOSED_STATUSES]
+    elif not include_closed:
+        docs = [doc for doc in docs if doc.status not in CLOSED_STATUSES]
+    followups: list[dict[str, object]] = []
+    patterns = ("Follow-up area:", "Product follow-up:", "Architecture follow-up:")
+    for doc in docs:
+        for index, line in enumerate(doc.content.splitlines(), start=1):
+            stripped = line.strip().lstrip("- ").strip()
+            matched = next((pattern for pattern in patterns if stripped.startswith(pattern)), None)
+            if not matched:
+                continue
+            text = stripped.removeprefix(matched).strip()
+            if not _is_actionable_followup(text):
+                continue
+            title = _slug_command_title(text)
+            quoted_title = shlex.quote(title)
+            followups.append(
+                {
+                    "source_ref": doc.ref,
+                    "source_path": doc.rel_path,
+                    "source_kind": doc.kind,
+                    "line": index,
+                    "text": text,
+                    "suggested_title": title,
+                    "suggested_command": f"python3 -m logics_manager flow new request --title {quoted_title}",
+                }
+            )
+    return {
+        "ok": True,
+        "count": len(followups),
+        "returned_count": min(len(followups), limit),
+        "filters": {
+            "source_kind": source_kind,
+            "include_closed": include_closed,
+            "closed_only": closed_only,
+        },
+        "followups": followups[:limit],
+    }
+
+
+def render_followups(
+    repo_root: Path,
+    *,
+    output_format: str = "text",
+    limit: int = 50,
+    source_kind: str = "all",
+    include_closed: bool = False,
+    closed_only: bool = False,
+) -> str:
+    payload = followups_payload(
+        repo_root,
+        limit=limit,
+        source_kind=source_kind,
+        include_closed=include_closed,
+        closed_only=closed_only,
+    )
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [f"Logics follow-ups: {payload['count']} found"]
+    for item in payload["followups"]:
+        lines.append(f"- {item['source_ref']}:{item['line']} {item['text']}")
+        lines.append(f"  command: {item['suggested_command']}")
+    return "\n".join(lines)
+
+
+def _related_ref(content: str, label: str) -> str | None:
+    prefix = f"> Related {label}:"
+    for line in content.splitlines():
+        if not line.startswith(prefix):
+            continue
+        value = line.split(":", 1)[1].strip()
+        normalized = value.strip("`").strip().lower()
+        if not normalized or normalized.startswith("(none"):
+            return None
+        match = re.search(r"`([^`]+)`", value)
+        return match.group(1) if match else value
+    return None
+
+
+def product_consistency_payload(repo_root: Path, *, limit: int = 50) -> dict[str, object]:
+    docs = collect_logics_docs(repo_root, kinds=WORKFLOW_KINDS + COMPANION_KINDS)
+    docs_by_ref = {doc.ref: doc for doc in docs}
+    product_docs = [doc for doc in docs if doc.kind == "product"]
+    checked_product_docs = [doc for doc in product_docs if doc.status != "Proposed"]
+    issues: list[dict[str, object]] = []
+    expected = {
+        "request": "request",
+        "backlog": "backlog",
+        "task": "task",
+    }
+    for doc in checked_product_docs:
+        missing_related: list[str] = []
+        broken_related: list[dict[str, str]] = []
+        for label, expected_kind in expected.items():
+            ref = _related_ref(doc.content, label)
+            if ref is None:
+                missing_related.append(label)
+                continue
+            target = docs_by_ref.get(ref)
+            if target is None:
+                broken_related.append({"kind": label, "ref": ref, "reason": "missing"})
+            elif target.kind != expected_kind:
+                broken_related.append({"kind": label, "ref": ref, "reason": f"expected {expected_kind}, found {target.kind}"})
+        if missing_related or broken_related:
+            issues.append(
+                {
+                    "ref": doc.ref,
+                    "title": doc.title,
+                    "status": doc.status,
+                    "path": doc.rel_path,
+                    "missing_related": missing_related,
+                    "broken_related": broken_related,
+                }
+            )
+    return {
+        "ok": not issues,
+        "product_count": len(product_docs),
+        "checked_product_count": len(checked_product_docs),
+        "skipped_product_count": len(product_docs) - len(checked_product_docs),
+        "issue_count": len(issues),
+        "issues": issues[:limit],
+        "truncated": len(issues) > limit,
+        "limit": limit,
+    }
+
+
+def render_product_consistency(repo_root: Path, *, output_format: str = "text", limit: int = 50) -> str:
+    payload = product_consistency_payload(repo_root, limit=limit)
+    if output_format == "json":
+        return json.dumps(payload, indent=2, sort_keys=True)
+
+    lines = [
+        "Product consistency:",
+        f"- product briefs: {payload['product_count']}",
+        f"- issue signals: {payload['issue_count']}",
+    ]
+    for issue in payload["issues"]:
+        details: list[str] = []
+        if issue["missing_related"]:
+            details.append("missing " + ", ".join(issue["missing_related"]))
+        if issue["broken_related"]:
+            details.append("broken " + ", ".join(item["ref"] for item in issue["broken_related"]))
+        lines.append(f"- {issue['ref']} [{issue['status']}]: {'; '.join(details)}")
+    return "\n".join(lines)

package/logics_manager/lint.py

@@ -578,12 +578,26 @@ def lint_payload(repo_root: Path, *, require_status: bool = False) -> dict[str,
             if warnings:
                 all_warnings.append((rel_path, warnings))
 
+    issues = [{"path": path.as_posix(), "message": issue, "severity": "blocking"} for path, issues in all_issues for issue in issues]
+    warnings: list[dict[str, str]] = []
+    for path, path_warnings in all_warnings:
+        for warning in path_warnings:
+            item = {"path": path.as_posix(), "message": warning, "severity": "warning"}
+            if "Mermaid context signature" in warning:
+                item["repair_command"] = "logics-manager sync refresh-mermaid-signatures"
+            warnings.append(item)
     return {
-        "ok": not all_issues,
-        "issue_count": sum(len(issues) for _path, issues in all_issues),
-        "warning_count": sum(len(warnings) for _path, warnings in all_warnings),
-        "issues": [{"path": path.as_posix(), "message": issue} for path, issues in all_issues for issue in issues],
-        "warnings": [{"path": path.as_posix(), "message": warning} for path, warnings in all_warnings for warning in warnings],
+        "ok": not issues,
+        "can_continue": not issues,
+        "release_ready": not issues and not warnings,
+        "issue_count": len(issues),
+        "warning_count": len(warnings),
+        "strict_count": 0,
+        "finding_count": len(issues) + len(warnings),
+        "issues": issues,
+        "warnings": warnings,
+        "strict": [],
+        "findings": [*issues, *warnings],
     }
 
 
@@ -594,11 +608,11 @@ def render_lint(repo_root: Path, *, require_status: bool = False, output_format:
     if not payload["issues"] and not payload["warnings"]:
         return "Logics lint: OK"
     if not payload["issues"]:
-        lines = ["Logics lint: OK (warnings)"]
+        lines = ["Logics lint: OK (warnings)", f"Blocking issues: {payload['issue_count']}; warnings: {payload['warning_count']}"]
         for warning in payload["warnings"]:
             lines.append(f"- {warning['path']}: WARNING: {warning['message']}")
         return "\n".join(lines)
-    lines = ["Logics lint: FAILED"]
+    lines = ["Logics lint: FAILED", f"Blocking issues: {payload['issue_count']}; warnings: {payload['warning_count']}"]
     for issue in payload["issues"]:
         lines.append(f"- {issue['path']}: {issue['message']}")
     for warning in payload["warnings"]: