procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/flowmodel/formdigest.py

@@ -0,0 +1,232 @@
+"""Readable Markdown digest of a PROCESIO form — its structure and its CONVERSATION with processes.
+
+A form talks to processes through element events (`on<Trigger>Events`) and form-level events
+(`Data.events`, e.g. FORM_LOAD). What an audit needs from each:
+  - RUN_PROCESS   : which process, sync or not, and the two maps — inputMap (process input
+                    variable <- form value) and outputMap (form value <- process output variable)
+  - MAP_FORM_DATA : which form values it sets to what, under which conditions
+  - RUN_JAVASCRIPT: the script (its header comment inline, the full body in a side file)
+  - anything else : the config, ids resolved
+
+Form values are addressed by dotted GUID paths into the form data model
+(`<form>.<root>.<elementId>.<attributeId>`, or a bare form-variable id). Every GUID segment is
+resolved to a name — elements by their designer `name`, attributes and variables by the data
+model — so a mapping reads `Table_EE.value <- extracted_table_rows`.
+
+Pure: dicts in, strings out. `processes` = {process_id: flow dict} to name process variables and
+titles; without it they stay GUIDs.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+_GUID = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
+_EVENT_KEY = re.compile(r"^on[A-Z]\w*Events$")
+_ROOT = "11223344-5566-7788-99aa-aabbccddeeff"   # the synthetic root model under `form`
+
+
+def unwrap(obj) -> dict:
+    """The form template dict from the API envelope or a bare template."""
+    if isinstance(obj, str):
+        obj = json.loads(obj)
+    if isinstance(obj, dict) and isinstance(obj.get("result"), dict):
+        obj = obj["result"]
+    return obj if isinstance(obj, dict) else {}
+
+
+def _data(form: dict) -> dict:
+    d = form.get("data") or form.get("Data") or {}
+    return json.loads(d) if isinstance(d, str) else d
+
+
+def _cfg(el: dict, key: str):
+    for c in el.get("configs") or []:
+        if c.get("key") == key:
+            return c.get("value")
+    return None
+
+
+class _Names:
+    def __init__(self, data: dict, processes: dict | None):
+        self.map: dict[str, str] = {}
+        self.process_vars: dict[str, dict[str, str]] = {}
+        self.titles: dict[str, str] = {}
+
+        def walk(node):
+            if isinstance(node, dict):
+                if node.get("id") and node.get("name"):
+                    self.map.setdefault(node["id"], node["name"])
+                for a in node.get("attributes") or []:
+                    walk(a)
+        walk(data.get("dataModel") or {})
+        for v in data.get("variables") or []:
+            if v.get("id"):
+                self.map[v["id"]] = v.get("name")
+        # element names win over their data-model node names (same GUID, clearer label)
+        for el in data.get("elements") or []:
+            n = _cfg(el, "name")
+            if el.get("id") and n:
+                self.map[el["id"]] = n
+        for pid, flow in (processes or {}).items():
+            self.titles[pid] = (flow.get("title") or "").strip()
+            self.process_vars[pid] = {v.get("id"): v.get("name") for v in flow.get("variables") or []}
+
+    def path(self, value) -> str:
+        """A dotted GUID path -> dotted names (form/root segments dropped)."""
+        if not isinstance(value, str) or not value:
+            return "∅" if value in (None, "") else json.dumps(value, ensure_ascii=False)
+        parts = value.split(".")
+        # drop the implicit `form` variable and the synthetic root model segment
+        while len(parts) > 1 and (self.map.get(parts[0]) == "form" or parts[0].startswith(_ROOT)):
+            parts = parts[1:]
+        return ".".join(self.map.get(p, p) for p in parts)
+
+    def text(self, s: str, pid: str | None = None) -> str:
+        pv = self.process_vars.get(pid or "", {})
+
+        def sub(m):
+            g = m.group(0)
+            return pv.get(g) or self.map.get(g) or (("[[" + self.titles[g] + "]]") if g in self.titles else g)
+        return _GUID.sub(sub, s)
+
+
+def _code_header(code: str) -> str:
+    """The script's leading comment block (how these scripts document themselves), else line 1."""
+    lines = code.strip().splitlines()
+    head = []
+    for ln in lines:
+        s = ln.strip()
+        if s.startswith(("//", "/*", "*")):
+            head.append(s.lstrip("/* ").rstrip())
+            if len(head) >= 4:
+                break
+        elif head or s:
+            break
+    head = [h for h in head if h and not set(h) <= set("=-─ ")]
+    return " / ".join(head)[:200] if head else (lines[0][:120] if lines else "")
+
+
+def _side(x):
+    """A map row / condition side is either `{"value": X}` or a bare `X`; real forms
+    use both shapes (a RUN_PROCESS map row often carries the value inline as a string)."""
+    return x.get("value") if isinstance(x, dict) else x
+
+
+def _conditions(conds, names: _Names) -> list[str]:
+    out = []
+    for c in conds or []:
+        left = _side(c.get("leftOperator"))
+        right = _side(c.get("rightOperator"))
+        join = {0: "", 1: "AND ", 2: "OR "}.get(c.get("logicOperator"), "")
+        r = f" {names.path(right)}" if right not in (None, "") else ""
+        out.append(f"{join}{names.path(left)} {c.get('operator')}{r}".strip())
+    return out
+
+
+def _event(ev: dict, names: _Names, scripts: list) -> list[str]:
+    act = ev.get("action")
+    cfg = ev.get("config") or {}
+    if act == "RUN_PROCESS":
+        pid = cfg.get("processId")
+        title = names.titles.get(pid) or pid
+        pv = names.process_vars.get(pid, {})
+        lines = [f"RUN_PROCESS → **{title}** ({'sync' if cfg.get('syncRun') else 'async'})"]
+        for m in cfg.get("inputMap") or []:
+            left = _side(m.get("left"))
+            lines.append(f"  - in: `{pv.get(left, left)}` ← `{names.path(_side(m.get('right')))}`")
+        for m in cfg.get("outputMap") or []:
+            left = _side(m.get("left"))
+            lines.append(f"  - out: `{names.path(_side(m.get('right')))}` ← `{pv.get(left, left)}`")
+        return lines
+    if act == "MAP_FORM_DATA":
+        lines = ["MAP_FORM_DATA"]
+        conds = _conditions(cfg.get("conditions"), names) if cfg.get("areConditionsConfigured") else []
+        if conds:
+            lines.append("  - when: " + " ".join(conds))
+        for m in cfg.get("mapping") or []:
+            lines.append(f"  - set `{names.path(m.get('left'))}` = `{names.path(m.get('right')) if _GUID.match(str(m.get('right') or '')) else m.get('right')}`")
+        return lines
+    if act == "RUN_JAVASCRIPT":
+        code = cfg.get("code") or ""
+        scripts.append(code)
+        return [f"RUN_JAVASCRIPT ({len(code)} chars, script #{len(scripts)}): {_code_header(code)}"]
+    return [f"{act}: `{names.text(json.dumps(cfg, ensure_ascii=False))[:400]}`"]
+
+
+def render(form: dict, processes: dict | None = None) -> tuple[str, list[str]]:
+    """(Markdown digest, [script bodies referenced as script #N])."""
+    data = _data(form)
+    names = _Names(data, processes)
+    els = data.get("elements") or []
+    kids: dict = {}
+    for e in els:
+        kids.setdefault(e.get("parentId"), []).append(e)
+    scripts: list[str] = []
+
+    lines = [f"# {form.get('name')}", "", f"- id: `{form.get('id')}`",
+             f"- status: {'published' if form.get('status') == 1 else 'draft'}, "
+             f"{'private' if form.get('isPrivate') else 'public'}",
+             f"- elements: {len(els)}"]
+    fvars = data.get("variables") or []
+    if fvars:
+        lines += ["", "## Form variables", ""]
+        for v in fvars:
+            if v.get("name") != "form":
+                lines.append(f"- `{v.get('name')}`{' (list)' if v.get('isList') else ''}"
+                             f"{' default=' + str(v.get('defaultValue')) if v.get('defaultValue') not in (None, '') else ''}")
+
+    fevents = data.get("events") or []
+    if fevents:
+        lines += ["", "## Form-level events", ""]
+        for ev in fevents:
+            body = _event(ev, names, scripts)
+            lines.append(f"- **{ev.get('type')}** → {body[0]}")
+            lines += ["  " + b for b in body[1:]]
+
+    lines += ["", "## Structure and element events", ""]
+
+    def walk(parent, depth):
+        for e in kids.get(parent, []):
+            name = _cfg(e, "name") or ""
+            dom = _cfg(e, "id")
+            label = _cfg(e, "label")
+            vis = _cfg(e, "visible")
+            bits = [f"{'  ' * depth}- **{e.get('type')}** `{name}`"]
+            if dom and dom != name:
+                bits.append(f"#{dom}")
+            if isinstance(label, str) and label and "<" not in label:
+                bits.append(f"“{label[:60]}”")
+            if vis is False:
+                bits.append("(hidden by default)")
+            lines.append(" ".join(bits))
+            for c in e.get("configs") or []:
+                v = c.get("value")
+                if _EVENT_KEY.match(c.get("key") or "") and isinstance(v, dict) and v.get("events"):
+                    trig = c["key"][2:-6]
+                    for ev in v["events"]:
+                        body = _event(ev, names, scripts)
+                        lines.append(f"{'  ' * (depth + 1)}- on {trig}: {body[0]}")
+                        lines.extend(f"{'  ' * (depth + 1)}{b}" for b in body[1:])
+            walk(e.get("id"), depth + 1)
+    walk(None, 0)
+    return "\n".join(lines) + "\n", scripts
+
+
+def process_links(form: dict) -> list[dict]:
+    """[{process_id, trigger, element}] for every RUN_PROCESS the form fires."""
+    data = _data(form)
+    out = []
+    for ev in data.get("events") or []:
+        if ev.get("action") == "RUN_PROCESS":
+            out.append({"process_id": (ev.get("config") or {}).get("processId"),
+                        "trigger": ev.get("type"), "element": "(form)"})
+    for e in data.get("elements") or []:
+        for c in e.get("configs") or []:
+            v = c.get("value")
+            if _EVENT_KEY.match(c.get("key") or "") and isinstance(v, dict):
+                for ev in v.get("events") or []:
+                    if ev.get("action") == "RUN_PROCESS":
+                        out.append({"process_id": (ev.get("config") or {}).get("processId"),
+                                    "trigger": c["key"][2:-6], "element": _cfg(e, "name")})
+    return out

procesio_cli/tools/procesio/flowmodel/inspect.py

@@ -0,0 +1,78 @@
+"""Curated structural summary of a flow, built on the graph reader + family map.
+
+Pure: parse → summarize. Reports counts, action families, branch map, subprocess calls,
+resources, the variable contract, and advisory smells (it reports; it does not fix).
+"""
+from __future__ import annotations
+
+import collections
+
+from tools.procesio.flowmodel import families, read_flow
+
+_LARGE_FLOW = 40                       # actions; above this, suggest splitting
+_DIRECTION = {10: "inputs", 20: "process", 30: "outputs", 40: "system", 50: "auto"}
+
+
+def inspect(source, flow_id: str | None = None) -> dict:
+    fg = read_flow(source, flow_id)
+
+    fam = collections.Counter(families.classify(n.template) for n in fg.nodes)
+    out0 = collections.Counter()
+    err_sources: set[str] = set()
+    for e in fg.edges:
+        if e.type == 1:
+            err_sources.add(e.source)
+        else:
+            out0[e.source] += 1
+
+    branches = []
+    for n in fg.nodes:
+        if n.shape == "diamond":
+            targets = sorted(e.dest for e in fg.edges if e.source == n.id and e.type == 0)
+            branches.append({"decisional_id": n.id, "cases": len(targets), "targets": targets})
+
+    counts = {
+        "actions": len(fg.nodes), "edges": len(fg.edges),
+        "decisionals": sum(1 for n in fg.nodes if n.shape == "diamond"),
+        "stops": len(fg.stop_ids),
+        "subprocess_calls": len(fg.subprocess_calls),
+        "foreach": sum(1 for c in fg.containers if c.kind == "foreach"),
+    }
+
+    variables = {"inputs": [], "process": [], "outputs": [], "system": [], "auto": [],
+                 "required": []}
+    for v in fg.variables:
+        bucket = _DIRECTION.get(v.type)
+        if bucket:
+            variables[bucket].append(v.name)
+        if v.is_required:
+            variables["required"].append(v.name)
+
+    smells = []
+    loop_kids = {kid for c in fg.containers for kid in c.children}
+    for n in fg.nodes:
+        family = families.classify(n.template)
+        if family == "integration" and n.id not in err_sources:
+            smells.append({"code": "no_error_port",
+                           "message": f"{n.template} (integration) has no error port wired",
+                           "action_id": n.id})
+        if n.id in loop_kids and family == "integration":
+            smells.append({"code": "slow_in_loop",
+                           "message": f"{n.template} runs inside a loop — cost multiplies per item",
+                           "action_id": n.id})
+    if len(fg.nodes) > _LARGE_FLOW:
+        smells.append({"code": "large_flow",
+                       "message": f"{len(fg.nodes)} actions — consider splitting into subprocesses"})
+    if variables["required"]:
+        smells.append({"code": "required_inputs",
+                       "message": "verify the trigger supplies the required inputs: "
+                                  + ", ".join(variables["required"])})
+
+    return {
+        "flow_id": fg.flow_id, "title": fg.title,
+        "counts": counts, "action_families": dict(fam),
+        "branches": branches,
+        "subprocess_calls": [{"action_id": s.action_id, "target_flow_id": s.target_flow_id,
+                              "kind": s.kind} for s in fg.subprocess_calls],
+        "resources": fg.resources, "variables": variables, "smells": smells,
+    }

procesio_cli/tools/procesio/flowmodel/model.py

@@ -0,0 +1,82 @@
+"""Canonical, JSON-ready graph model for a PROCESIO flow.
+
+Plain dataclasses so Python consumers (the layout adapter, inspect-flow) get typed
+objects, and `to_dict()` yields the JSON the `read-flow-graph` action emits. Pure data,
+no behavior beyond serialization.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+
+
+@dataclass
+class Node:
+    id: str
+    template: str | None
+    shape: str | None          # "square" | "diamond" | "circle" | "area" (action-dictated)
+    icon: str | None
+    position: dict              # {"x": float, "y": float}
+    size: dict                 # {"w": float, "h": float}
+    parent_id: str | None
+    input_ports: int | None
+    output_ports: int | None
+    disabled: bool = False
+
+
+@dataclass
+class Edge:
+    source: str
+    dest: str
+    type: int                  # 0 = normal flow edge, 1 = error-port edge
+    is_default: bool = False    # the decisional's Default branch (port.data.isDefault=='default')
+
+    @property
+    def is_error(self) -> bool:
+        return self.type == 1
+
+
+@dataclass
+class Container:
+    id: str                    # the For-Each area node id
+    kind: str                  # "foreach"
+    children: list[str] = field(default_factory=list)
+    size: dict = field(default_factory=dict)
+
+
+@dataclass
+class VarRef:
+    id: str
+    name: str | None
+    type: int | None
+    data_type: str | None
+    is_list: bool = False
+    is_required: bool = False
+    is_error: bool = False
+
+
+@dataclass
+class SubprocessCall:
+    action_id: str
+    target_flow_id: str | None
+    kind: str                  # "call" | "trigger"
+
+
+@dataclass
+class FlowGraph:
+    flow_id: str | None
+    title: str | None
+    nodes: list[Node] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+    containers: list[Container] = field(default_factory=list)
+    variables: list[VarRef] = field(default_factory=list)
+    subprocess_calls: list[SubprocessCall] = field(default_factory=list)
+    resources: dict = field(default_factory=lambda: {"credentials": [], "webhooks": [], "documents": []})
+    start_id: str | None = None
+    stop_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        # surface the convenience flag on edges
+        for e_in, e_out in zip(self.edges, d["edges"]):
+            e_out["is_error"] = e_in.is_error
+        return d