devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/registry/enforce_report.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+"""Build a unified enforcement report from the registry DB.
+
+Enforcement is gate-only: it must not run LLM classification or change policy.
+It may derive facts from the current import graph + persisted policy.
+
+Report format is designed to be consumed by `devflow refactor`.
+"""
+
+from collections import defaultdict
+
+
+def build_enforce_report(conn, *, changed_importers: set[str] | None = None) -> dict[str, object]:
+    """Return a machine-readable enforcement report.
+
+    conn is a sqlite3 connection with registry schema.
+    changed_importers (optional) restricts the report to imports originating from
+    those importer file paths (repo-relative).
+    """
+
+    changed_importers = {str(p) for p in (changed_importers or set())}
+
+    def _importer_ok(importer: str) -> bool:
+        return (not changed_importers) or (importer in changed_importers)
+
+    # Missing registration (existing helper query semantics)
+    missing: list[dict[str, str]] = []
+
+    # external missing
+    for importer, specifier, resolved_id in conn.execute(
+        """
+        SELECT importer, specifier, resolved_id
+        FROM imports
+        WHERE kind='external'
+        AND substr(resolved_id, 5) NOT IN (SELECT name FROM allowed_packages)
+        ORDER BY importer, specifier
+        """
+    ).fetchall():
+        if not _importer_ok(str(importer)):
+            continue
+        missing.append({"importer": str(importer), "specifier": str(specifier), "resolved_id": str(resolved_id), "kind": "external"})
+
+    # internal missing
+    for importer, specifier, resolved_id in conn.execute(
+        """
+        SELECT importer, specifier, resolved_id
+        FROM imports
+        WHERE kind='internal'
+        AND resolved_id NOT IN (SELECT item_id FROM registered_items)
+        ORDER BY importer, specifier
+        """
+    ).fetchall():
+        if not _importer_ok(str(importer)):
+            continue
+        missing.append({"importer": str(importer), "specifier": str(specifier), "resolved_id": str(resolved_id), "kind": "internal"})
+
+    # Canonical refactor directives
+    directives: list[dict[str, object]] = []
+
+    # Packages: if a package is marked heretical, tell the user to refactor to the canonical for that domain/lane.
+    pkg_status: dict[str, tuple[str, str, str]] = {}
+    for package, domain, status, lane in conn.execute(
+        "select package, domain, status, coalesce(lane,'') from package_status where domain is not null"
+    ).fetchall():
+        pkg_status[str(package)] = (str(domain), str(status), str(lane or ""))
+
+    canonical_by_domain_lane: dict[tuple[str, str], str] = {}
+    for package, domain, status, lane in conn.execute(
+        "select package, domain, status, coalesce(lane,'') from package_status where status='canonical' and domain is not null"
+    ).fetchall():
+        canonical_by_domain_lane[(str(domain), str(lane or ""))] = str(package)
+
+    for importer, specifier, resolved_id in conn.execute(
+        "select importer, specifier, resolved_id from imports where kind='external' order by importer, specifier"
+    ).fetchall():
+        if not _importer_ok(str(importer)):
+            continue
+        pkg = str(resolved_id).split(":", 1)[1]
+        st = pkg_status.get(pkg)
+        if not st:
+            continue
+        domain, status, lane = st
+        if status != "heretical":
+            continue
+        canon = canonical_by_domain_lane.get((domain, lane)) or canonical_by_domain_lane.get((domain, ""))
+        if not canon or canon == pkg:
+            continue
+        directives.append(
+            {
+                "kind": "refactor_external_package",
+                "domain": domain,
+                "lane": lane,
+                "from": pkg,
+                "to": canon,
+                "evidence": {"importer": str(importer), "specifier": str(specifier)},
+            }
+        )
+
+    # Modules: if an imported module is heretical in an existing (domain, card_id, lane), refactor to canonical.
+    canon_module_by_key: dict[tuple[str, str, str], str] = {}
+    for domain, card_id, lane, module_id in conn.execute(
+        "select domain, card_id, lane, module_id from module_card_membership where status='canonical'"
+    ).fetchall():
+        canon_module_by_key[(str(domain), str(card_id), str(lane))] = str(module_id)
+
+    membership: dict[tuple[str, str, str, str], str] = {}
+    for domain, card_id, lane, module_id, status in conn.execute(
+        "select domain, card_id, lane, module_id, status from module_card_membership"
+    ).fetchall():
+        membership[(str(domain), str(card_id), str(lane), str(module_id))] = str(status)
+
+    # Build quick module -> keys where it is heretical.
+    heretical_keys_by_module: dict[str, list[tuple[str, str, str]]] = defaultdict(list)
+    for (domain, card_id, lane, module_id), status in membership.items():
+        if status == "heretical":
+            heretical_keys_by_module[module_id].append((domain, card_id, lane))
+
+    for importer, specifier, resolved_id in conn.execute(
+        "select importer, specifier, resolved_id from imports where kind='internal' order by importer, specifier"
+    ).fetchall():
+        if not _importer_ok(str(importer)):
+            continue
+        mid = str(resolved_id)
+        for key in heretical_keys_by_module.get(mid, []):
+            canon = canon_module_by_key.get(key)
+            if not canon or canon == mid:
+                continue
+            domain, card_id, lane = key
+            directives.append(
+                {
+                    "kind": "refactor_internal_module",
+                    "domain": domain,
+                    "card_id": card_id,
+                    "lane": lane,
+                    "from": mid,
+                    "to": canon,
+                    "evidence": {"importer": str(importer), "specifier": str(specifier)},
+                }
+            )
+
+    directives.sort(key=lambda d: (str(d.get("kind")), str(d.get("domain")), str(d.get("from")), str(d.get("to")), str(d.get("evidence", {}).get("importer"))))
+
+    ok = (not missing) and (not directives)
+    return {
+        "ok": bool(ok),
+        "missing": missing,
+        "directives": directives,
+        "stats": {"missing": len(missing), "directives": len(directives)},
+    }

devflow_engine/registry/module_cards_classify.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+"""Module-card classification (non-destructive).
+
+Takes a draft module-card plan and produces a classified plan:
+- assigns each card a domain
+- assigns each module within card a lane
+- marks exactly one canonical per (domain, card_id, lane)
+
+This mirrors the package policy model (domain + lane + canonical/heretical),
+but remains file-based until we decide to persist it.
+"""
+
+import json
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ClassifiedAssignment:
+    card_id: str
+    domain: str
+    module_id: str
+    lane: str
+    status: str  # canonical|heretical
+    reason: str
+
+
+def _extract_json(text: str) -> str | None:
+    # Common case: model wraps JSON in ```json fences.
+    if "```" in text:
+        parts = text.split("```")
+        for i in range(len(parts) - 1):
+            body = parts[i + 1]
+            body_lines = body.splitlines()
+            if body_lines and body_lines[0].strip().lower() in {"json", "javascript"}:
+                body = "\n".join(body_lines[1:])
+            body = body.strip()
+            if body.startswith("{") and body.endswith("}"):
+                return body
+
+    start = text.find("{")
+    end = text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        return text[start : end + 1]
+
+    return None
+
+
+def build_classify_prompt(*, draft: dict[str, object], domain_enum: list[str] | None = None, allow_new_domains: bool = True) -> str:
+    cards = draft.get("cards") if isinstance(draft, dict) else None
+    if not isinstance(cards, list):
+        cards = []
+
+    # Keep prompt small: only include cards with >1 module (i.e., overlaps).
+    overlap_cards: list[dict[str, object]] = []
+    for c in cards:
+        if not isinstance(c, dict):
+            continue
+        canon = str(c.get("canonical_module_id") or "").strip()
+        comps = c.get("competing_module_ids")
+        if not canon:
+            continue
+        if not isinstance(comps, list) or not comps:
+            continue
+        overlap_cards.append(
+            {
+                "card_id": str(c.get("card_id") or "").strip(),
+                "canonical_module_id": canon,
+                "competing_module_ids": [str(x) for x in comps if str(x)],
+                "evidence": c.get("evidence") if isinstance(c.get("evidence"), dict) else {},
+            }
+        )
+
+    instructions = [
+        "Return JSON only (no markdown, no code fences).",
+        "For each card, choose a domain.",
+        "Lane assignment is the primary goal. Prefer splitting into semantically distinct lanes over marking heresy.",
+        "For each module in a card (canonical + competing), assign a lane string.",
+        "If two modules are different abstraction levels (primitive vs composite), different surfaces (provider vs consumer), or different sub-flows, they should be in different lanes.",
+        "Only when two modules genuinely represent the same concern within the same lane should you mark one canonical and all others heretical.",
+        "Within each lane of a card, mark exactly one module as canonical and all other modules in that lane heretical.",
+        "Minimize heretical assignments; use them only when lane splitting cannot be justified.",
+        "Keep lane names short but expressive; hierarchical lanes are allowed (e.g. navigation.top, navigation.bottom, controls.primitive, controls.composite, context.provider, page.consumer).",
+    ]
+
+    if allow_new_domains:
+        instructions.extend(
+            [
+                "You MAY propose a new domain if none of domain_enum fit.",
+                "If proposing a new domain, include new_domain with that value (and also set domain to that value).",
+                "New domains must be 1-2 words, general (not project-specific), lowercase, and avoid version suffixes.",
+            ]
+        )
+    else:
+        instructions.extend(
+            [
+                "You MUST choose domain from domain_enum. Do not create new domains.",
+            ]
+        )
+
+    payload: dict[str, object] = {
+        "task": "classify_module_cards",
+        "domain_enum": domain_enum or [],
+        "allow_new_domains": bool(allow_new_domains),
+        "cards": overlap_cards,
+        "instructions": instructions,
+        "output_schema": {
+            "assignments": [
+                {
+                    "card_id": "string",
+                    "domain": "string",
+                    "new_domain": "string|null",
+                    "module_id": "string",
+                    "lane": "string",
+                    "status": "canonical|heretical",
+                    "reason": "string",
+                }
+            ]
+        },
+    }
+
+    return json.dumps(payload, indent=2, sort_keys=True)
+
+
+def parse_classified_output(*, out_text: str) -> dict[str, object]:
+    raw = _extract_json(out_text)
+    if raw is None:
+        raise ValueError("Failed to locate JSON in LLM output")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise ValueError("LLM output must be a JSON object")
+    assignments = parsed.get("assignments")
+    if not isinstance(assignments, list):
+        raise ValueError("LLM output missing assignments[]")
+
+    cleaned: list[dict[str, object]] = []
+    for a in assignments:
+        if not isinstance(a, dict):
+            continue
+        card_id = str(a.get("card_id") or "").strip()
+        domain = str(a.get("domain") or "").strip()
+        new_domain = str(a.get("new_domain") or "").strip() or None
+        module_id = str(a.get("module_id") or "").strip()
+        lane = str(a.get("lane") or "").strip()
+        status = str(a.get("status") or "").strip().lower()
+        reason = str(a.get("reason") or "").strip()
+        if not (card_id and domain and module_id and lane and status in {"canonical", "heretical"}):
+            continue
+        cleaned.append(
+            {
+                "card_id": card_id,
+                "domain": domain,
+                "new_domain": new_domain,
+                "module_id": module_id,
+                "lane": lane,
+                "status": status,
+                "reason": reason,
+            }
+        )
+
+    cleaned.sort(key=lambda r: (str(r["domain"]), str(r["card_id"]), str(r["lane"]), str(r["status"]), str(r["module_id"])))
+
+    new_domains = sorted({str(r["new_domain"]) for r in cleaned if r.get("new_domain")})
+    return {"version": 2, "new_domains": new_domains, "assignments": cleaned}

devflow_engine/registry/module_cards_draft.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+"""Draft module-card registration artifacts.
+
+This is intentionally *non-destructive*: it does not write to the registry DB.
+It produces a stable JSON draft you can inspect, edit, and later "apply".
+
+A draft card is keyed by (domain, card_id, lane) and has exactly one canonical seam.
+In v0 drafts, domain is "unknown" and lane is "default".
+"""
+
+import re
+from dataclasses import dataclass
+
+from .pathways import ModuleSignals, build_module_graph, detect_pathways
+
+
+@dataclass(frozen=True)
+class DraftCard:
+    card_id: str
+    domain: str
+    lane: str
+    canonical_module_id: str
+    competing_module_ids: tuple[str, ...]
+    evidence: dict[str, object]
+
+
+def _slugify(text: str) -> str:
+    t = text.strip().lower()
+    t = re.sub(r"[^a-z0-9]+", "-", t)
+    t = re.sub(r"-+", "-", t).strip("-")
+    return t or "card"
+
+
+def _module_basename(module_id: str) -> str:
+    s = module_id.split(":", 1)[-1]
+    return s.split("/")[-1]
+
+
+def _choose_canonical(module_ids: list[str], g: dict[str, ModuleSignals]) -> str:
+    # Deterministic: highest in_degree, tie-break by module_id.
+    return sorted(module_ids, key=lambda mid: (-(g.get(mid).in_degree if g.get(mid) else 0), mid))[0]
+
+
+def draft_module_cards(
+    *,
+    imports_rows: list[tuple[str, str, str, str]],
+    module_exports: dict[str, list[str]] | None = None,
+    module_external_pkgs: dict[str, list[str]] | None = None,
+    module_effect_tokens: dict[str, list[str]] | None = None,
+    focus_module_ids: set[str] | None = None,
+    domain_default: str = "unknown",
+    lane_default: str = "default",
+) -> dict[str, object]:
+    """Generate a stable draft module-card plan from import graph signals."""
+
+    report = detect_pathways(
+        imports_rows=imports_rows,
+        module_exports=module_exports,
+        module_external_pkgs=module_external_pkgs,
+        module_effect_tokens=module_effect_tokens,
+    )
+
+    g = build_module_graph(
+        imports_rows=imports_rows,
+        module_exports=module_exports,
+        module_external_pkgs=module_external_pkgs,
+    )
+
+    # Build undirected components from competing pairs.
+    # We include both:
+    # - "competing" hubs (shared importer neighborhoods)
+    # - "effect_overlap" competing pairs (shared effect signatures)
+    adj: dict[str, set[str]] = {}
+
+    def _add_edge(a: str, b: str) -> None:
+        if not a or not b:
+            return
+        adj.setdefault(a, set()).add(b)
+        adj.setdefault(b, set()).add(a)
+
+    for p in report.get("competing", []):
+        _add_edge(str(p.get("a") or ""), str(p.get("b") or ""))
+
+    eo = report.get("effect_overlap", {})
+    if isinstance(eo, dict):
+        for p in eo.get("pairs", []) if isinstance(eo.get("pairs"), list) else []:
+            if not isinstance(p, dict):
+                continue
+            if str(p.get("kind") or "") != "competing":
+                continue
+            _add_edge(str(p.get("a") or ""), str(p.get("b") or ""))
+
+    visited: set[str] = set()
+    groups: list[list[str]] = []
+
+    for n in sorted(adj.keys()):
+        if n in visited:
+            continue
+        stack = [n]
+        comp: set[str] = set()
+        while stack:
+            cur = stack.pop()
+            if cur in visited:
+                continue
+            visited.add(cur)
+            comp.add(cur)
+            for nxt in adj.get(cur, set()):
+                if nxt not in visited:
+                    stack.append(nxt)
+        if len(comp) >= 2:
+            groups.append(sorted(comp))
+
+    # Any hub seams not in a competing group become singleton cards.
+    hub_ids: list[str] = []
+    for s in report.get("seams", []):
+        if isinstance(s, dict) and s.get("kind") == "hub":
+            hub_ids.append(str(s.get("module_id") or ""))
+    hub_ids = [h for h in hub_ids if h]
+
+    grouped = {m for grp in groups for m in grp}
+    for h in sorted(set(hub_ids)):
+        if h not in grouped:
+            groups.append([h])
+
+    focus_module_ids = focus_module_ids or None
+
+    # Draft cards
+    cards: list[dict[str, object]] = []
+    for grp in groups:
+        if focus_module_ids is not None:
+            if not any(m in focus_module_ids for m in grp):
+                continue
+        canonical = _choose_canonical(grp, g)
+        competitors = [m for m in grp if m != canonical]
+
+        # Stable-ish card id based on canonical basename + first few competitors.
+        parts = [_module_basename(canonical)] + [_module_basename(m) for m in competitors[:2]]
+        card_id = _slugify("-".join(parts))
+
+        evidence = {
+            "canonical": {
+                "module_id": canonical,
+                "in_degree": g.get(canonical).in_degree if g.get(canonical) else 0,
+                "out_degree": g.get(canonical).out_degree if g.get(canonical) else 0,
+                "top_importers": list(g.get(canonical).importers)[:10] if g.get(canonical) else [],
+            },
+            "competing": [
+                {
+                    "module_id": m,
+                    "in_degree": g.get(m).in_degree if g.get(m) else 0,
+                    "out_degree": g.get(m).out_degree if g.get(m) else 0,
+                }
+                for m in competitors
+            ],
+        }
+
+        cards.append(
+            {
+                "card_id": card_id,
+                "domain": domain_default,
+                "lane": lane_default,
+                "canonical_module_id": canonical,
+                "competing_module_ids": competitors,
+                "evidence": evidence,
+            }
+        )
+
+    cards.sort(key=lambda c: (str(c.get("domain")), str(c.get("lane")), str(c.get("card_id"))))
+
+    return {
+        "version": 1,
+        "stats": {
+            "cards": len(cards),
+            "source_modules": report.get("stats", {}).get("modules"),
+            "source_hubs": report.get("stats", {}).get("hubs"),
+            "source_competing_pairs": report.get("stats", {}).get("competing_pairs"),
+            "source_effect_overlap_pairs": report.get("stats", {}).get("effect_overlap_pairs"),
+        },
+        "cards": cards,
+        "raw": {
+            "pathways": report,
+        },
+    }

devflow_engine/registry/module_cards_gate.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+"""Deterministic gate for classified module cards."""
+
+from collections import defaultdict
+
+
+def gate_classified_module_cards(doc: dict[str, object]) -> dict[str, object]:
+    assignments = doc.get("assignments") if isinstance(doc, dict) else None
+    if not isinstance(assignments, list):
+        return {"ok": False, "violations": [{"kind": "invalid_format", "message": "missing assignments[]"}]}
+
+    violations: list[dict[str, object]] = []
+
+    # Validate required fields and group by (domain, card_id, lane)
+    by_key: dict[tuple[str, str, str], list[dict[str, str]]] = defaultdict(list)
+    seen_module_in_card: set[tuple[str, str]] = set()  # (card_id, module_id)
+
+    for a in assignments:
+        if not isinstance(a, dict):
+            continue
+        card_id = str(a.get("card_id") or "").strip()
+        domain = str(a.get("domain") or "").strip()
+        module_id = str(a.get("module_id") or "").strip()
+        lane = str(a.get("lane") or "").strip()
+        status = str(a.get("status") or "").strip().lower()
+
+        if not card_id or not domain or not module_id or not lane:
+            violations.append({"kind": "missing_fields", "assignment": a})
+            continue
+        if status not in {"canonical", "heretical"}:
+            violations.append({"kind": "invalid_status", "assignment": a})
+            continue
+
+        if (card_id, module_id) in seen_module_in_card:
+            violations.append({"kind": "duplicate_module", "card_id": card_id, "module_id": module_id})
+            continue
+        seen_module_in_card.add((card_id, module_id))
+
+        by_key[(domain, card_id, lane)].append(
+            {"module_id": module_id, "status": status}
+        )
+
+    # Convergence per lane.
+    for (domain, card_id, lane), items in sorted(by_key.items()):
+        canon = [i["module_id"] for i in items if i["status"] == "canonical"]
+        if len(canon) != 1:
+            violations.append(
+                {
+                    "kind": "lane_not_converged",
+                    "domain": domain,
+                    "card_id": card_id,
+                    "lane": lane,
+                    "canonicals": canon,
+                    "members": sorted(items, key=lambda r: (r["status"], r["module_id"])) ,
+                }
+            )
+
+    return {"ok": not violations, "violations": violations}