flowforge-map 0.1.0__py3-none-any.whl

flowforge/flow/index.py

@@ -0,0 +1,116 @@
+"""Every Python function in the repo, and which in-repo function each call reaches (D25). Read by `ast`, never run."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+
+
+@dataclass
+class Func:
+    module: str                     # "services.geo"
+    path: str                       # "services/geo.py"
+    name: str                       # "find_place", or "Class.method"
+    node: ast.FunctionDef | ast.AsyncFunctionDef
+
+    @property
+    def key(self) -> str:
+        return f"{self.module}.{self.name}"
+
+
+@dataclass
+class Module:
+    name: str
+    path: str
+    tree: ast.Module
+    aliases: dict[str, str] = field(default_factory=dict)   # local name -> dotted name it was imported as
+    uses_mcp: bool = False                                  # imports the MCP SDK
+
+
+def module_name(path: str) -> str:
+    parts = list(PurePosixPath(path).with_suffix("").parts)
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)
+
+
+def _imports(module: Module) -> None:
+    package = module.name.rsplit(".", 1)[0] if "." in module.name else ""
+    for node in ast.walk(module.tree):
+        if isinstance(node, ast.Import):
+            for a in node.names:
+                module.aliases[(a.asname or a.name).split(".")[0]] = a.name if a.asname else a.name.split(".")[0]
+                module.uses_mcp |= a.name == "mcp" or a.name.startswith("mcp.")
+        elif isinstance(node, ast.ImportFrom):
+            base = node.module or ""
+            if node.level:   # relative: from .geo import x
+                up = package.split(".")[: max(0, len(package.split(".")) - node.level + 1)] if package else []
+                base = ".".join([*up, base] if base else up)
+            module.uses_mcp |= base == "mcp" or base.startswith("mcp.")
+            for a in node.names:
+                module.aliases[a.asname or a.name] = f"{base}.{a.name}" if base else a.name
+
+
+class Index:
+    """The repo's functions. `resolve` turns a call into the in-repo function it runs, or None."""
+
+    def __init__(self, sources: dict[str, str]):
+        self.modules: dict[str, Module] = {}
+        self.funcs: dict[str, Func] = {}
+        for path, text in sources.items():
+            try:
+                tree = ast.parse(text)
+            except SyntaxError:
+                continue
+            module = Module(module_name(path), path, tree)
+            _imports(module)
+            self.modules[module.name] = module
+            for node in tree.body:
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    self._add(Func(module.name, path, node.name, node))
+                elif isinstance(node, ast.ClassDef):
+                    for item in node.body:
+                        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                            self._add(Func(module.name, path, f"{node.name}.{item.name}", item))
+
+    def _add(self, func: Func) -> None:
+        self.funcs[func.key] = func
+
+    def _known(self, dotted: str) -> str | None:
+        if dotted in self.funcs:
+            return dotted
+        # a src/ layout or a run from a subfolder: match on the trailing parts
+        ends = [k for k in self.funcs if k.endswith("." + dotted)]
+        return ends[0] if len(ends) == 1 else None
+
+    def resolve(self, call: ast.Call, module: Module, cls: str | None = None) -> str | None:
+        f = call.func
+        if isinstance(f, ast.Name):
+            local = f"{module.name}.{f.id}"
+            if local in self.funcs:
+                return local
+            if f.id in module.aliases:
+                return self._known(module.aliases[f.id])
+            return None
+        if isinstance(f, ast.Attribute) and isinstance(f.value, ast.Name):
+            owner = f.value.id
+            if owner == "self" and cls:
+                return self._known(f"{module.name}.{cls}.{f.attr}")
+            if owner in module.aliases:
+                return self._known(f"{module.aliases[owner]}.{f.attr}")
+            local_class = f"{module.name}.{owner}.{f.attr}"
+            if local_class in self.funcs:
+                return local_class
+        return None
+
+    def callers(self) -> dict[str, set[str]]:
+        """func key -> keys of the in-repo functions that call it (module-level code is not a caller)."""
+        out: dict[str, set[str]] = {k: set() for k in self.funcs}
+        for func in self.funcs.values():
+            module = self.modules[func.module]
+            cls = func.name.split(".")[0] if "." in func.name else None
+            for node in ast.walk(func.node):
+                if isinstance(node, ast.Call) and (target := self.resolve(node, module, cls)) and target != func.key:
+                    out[target].add(func.key)
+        return out

flowforge/flow/order.py

@@ -0,0 +1,181 @@
+"""The order one entry function calls its dependencies (D25): statements, what each reads and writes, the `if`s
+around them and the early returns before them, projected onto the blocks the map draws.
+
+A line A → B means B can't start before A is done: it reads something A wrote (directly or through plain code in
+between), it sits in an `if` A decides, or A returns early and B comes after. Lines are transitively reduced.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field
+
+from flowforge.flow.index import Func, Index
+from flowforge.flow.reach import Hit, Reach, gathers
+
+MUTATORS = frozenset({"append", "extend", "update", "add", "insert", "pop", "remove", "clear", "setdefault", "write",
+                      "sort", "discard", "appendleft", "put"})
+
+
+@dataclass
+class Stmt:
+    idx: int
+    node: ast.AST                 # a simple statement, or an `if`'s test, or a loop / with header
+    line: int
+    reads: set[str]
+    writes: set[str]
+    hits: list[Hit]
+    ifs: list[tuple[int, str]]    # enclosing (if statement, "yes" | "no"), outermost first
+    loop: bool = False
+    returns: bool = False
+    gathered: bool = False
+    is_if: bool = False
+    block_end: int = -1           # an `if`: index of the last statement inside it
+    stops: str | None = None      # an `if` that returns early: the branch that returns ("yes" | "no")
+    stop_line: int = 0
+
+
+def _reads(node: ast.AST) -> set[str]:
+    return {n.id for n in ast.walk(node) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Load)}
+
+
+def _writes(node: ast.AST) -> set[str]:
+    out = {n.id for n in ast.walk(node) if isinstance(n, ast.Name) and isinstance(n.ctx, (ast.Store, ast.Del))}
+    for n in ast.walk(node):
+        if isinstance(n, (ast.Subscript, ast.Attribute)) and isinstance(n.ctx, ast.Store):
+            base = n.value
+            while isinstance(base, (ast.Subscript, ast.Attribute)):
+                base = base.value
+            if isinstance(base, ast.Name):
+                out.add(base.id)
+        if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and n.func.attr in MUTATORS \
+                and isinstance(n.func.value, ast.Name):
+            out.add(n.func.value.id)   # facts.append(x) writes facts
+    return out
+
+
+@dataclass
+class Body:
+    """One function's statements, flattened in source order."""
+
+    func: Func
+    stmts: list[Stmt] = field(default_factory=list)
+
+
+def flatten(func: Func, index: Index, reach: Reach) -> Body:
+    module = index.modules[func.module]
+    cls = func.name.split(".")[0] if "." in func.name else None
+    body = Body(func)
+
+    def add(node: ast.AST, line: int, ifs: list[tuple[int, str]], loop: bool, *, reads: set[str] | None = None,
+            writes: set[str] | None = None, hit_node: ast.AST | None = None, is_if: bool = False) -> Stmt:
+        s = Stmt(idx=len(body.stmts), node=node, line=line, reads=_reads(node) if reads is None else reads,
+                 writes=_writes(node) if writes is None else writes,
+                 hits=reach.statement(hit_node if hit_node is not None else node, module, cls) if hit_node is not False
+                 else [], ifs=list(ifs), loop=loop, returns=isinstance(node, (ast.Return, ast.Raise)),
+                 gathered=gathers(node), is_if=is_if)
+        body.stmts.append(s)
+        return s
+
+    def walk(stmts: list[ast.stmt], ifs: list[tuple[int, str]], loop: bool) -> None:
+        for st in stmts:
+            if isinstance(st, ast.If):
+                test = add(st.test, st.lineno, ifs, loop, is_if=True)
+                first = len(body.stmts)
+                walk(st.body, [*ifs, (test.idx, "yes")], loop)
+                after_body = len(body.stmts)
+                walk(st.orelse, [*ifs, (test.idx, "no")], loop)
+                test.block_end = len(body.stmts) - 1
+                returns_yes = next((s for s in body.stmts[first:after_body] if s.returns and not s.loop), None)
+                returns_no = next((s for s in body.stmts[after_body:] if s.returns and not s.loop), None)
+                if returns_yes and not returns_no:
+                    test.stops, test.stop_line = "yes", returns_yes.line
+                elif returns_no and not returns_yes:
+                    test.stops, test.stop_line = "no", returns_no.line
+            elif isinstance(st, (ast.For, ast.AsyncFor)):
+                add(st.iter, st.lineno, ifs, loop, writes=_writes(st.target) | {n.id for n in ast.walk(st.target)
+                                                                             if isinstance(n, ast.Name)})
+                walk(st.body, ifs, True)
+                walk(st.orelse, ifs, loop)
+            elif isinstance(st, ast.While):
+                add(st.test, st.lineno, ifs, loop, writes=set())
+                walk(st.body, ifs, True)
+                walk(st.orelse, ifs, loop)
+            elif isinstance(st, (ast.With, ast.AsyncWith)):
+                header = ast.Tuple(elts=[i.context_expr for i in st.items], ctx=ast.Load())
+                ast.copy_location(header, st)
+                names = {n.id for i in st.items if i.optional_vars is not None for n in ast.walk(i.optional_vars)
+                         if isinstance(n, ast.Name)}
+                add(header, st.lineno, ifs, loop, writes=names)
+                walk(st.body, ifs, loop)
+            elif isinstance(st, ast.Try) or type(st).__name__ == "TryStar":
+                walk(st.body, ifs, loop)
+                for handler in st.handlers:
+                    walk(handler.body, ifs, loop)
+                walk(st.orelse, ifs, loop)
+                walk(st.finalbody, ifs, loop)
+            elif isinstance(st, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                add(st, st.lineno, ifs, loop, reads=set(), writes={st.name}, hit_node=False)
+            else:
+                add(st, st.lineno, ifs, loop)
+
+    walk(func.node.body, [], False)
+    return body
+
+
+def label(stmt: Stmt, index: Index, module_name: str) -> str:
+    """The code's own words for a step: a string it passes (`attempt("find the city (Nominatim)", …)`), without the
+    trailing note in brackets; else the function it calls, as words (`packing_list` → "packing list")."""
+    for sub in ast.walk(stmt.node):
+        if isinstance(sub, ast.Call):
+            for arg in sub.args:
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str) and " " in arg.value.strip():
+                    return re.sub(r"\s*\([^)]*\)\s*$", "", arg.value.strip())[:120]
+    for sub in ast.walk(stmt.node):
+        if isinstance(sub, ast.Call):
+            target = index.resolve(sub, index.modules[module_name])
+            if target:
+                return target.rsplit(".", 1)[-1].replace("_", " ").strip()
+    return ""
+
+
+def preds(body: Body) -> dict[int, list[tuple[int, str | None]]]:
+    """Statement-level: what each statement waits for, and the branch label when it is an `if`'s own control."""
+    out: dict[int, list[tuple[int, str | None]]] = {}
+    for s in body.stmts:
+        found: dict[int, str | None] = {}
+        for name in s.reads:
+            for t in body.stmts[: s.idx]:
+                if name in t.writes:
+                    found.setdefault(t.idx, None)
+        if s.ifs:
+            d, lab = s.ifs[-1]
+            found[d] = lab
+        for g in body.stmts[: s.idx]:
+            if g.stops and g.block_end < s.idx and all(i != g.idx for i, _ in s.ifs):
+                found[g.idx] = "no" if g.stops == "yes" else "yes"   # the branch that carries on
+        out[s.idx] = sorted(found.items())
+    return out
+
+
+def reduce(edges: set[tuple[str, str]]) -> set[tuple[str, str]]:
+    """Transitive reduction of a DAG: drop A → C when A reaches C another way."""
+    children: dict[str, set[str]] = {}
+    for a, b in edges:
+        children.setdefault(a, set()).add(b)
+
+    def reaches(a: str, target: str, skip: tuple[str, str]) -> bool:
+        stack, seen = [a], set()
+        while stack:
+            here = stack.pop()
+            for nxt in children.get(here, ()):
+                if (here, nxt) == skip or nxt in seen:
+                    continue
+                if nxt == target:
+                    return True
+                seen.add(nxt)
+                stack.append(nxt)
+        return False
+
+    return {e for e in edges if not reaches(e[0], e[1], e)}

flowforge/flow/reach.py

@@ -0,0 +1,145 @@
+"""Which dependencies a statement or a function reaches (D25), from the scan's own places (D21).
+
+A place counts only when it shows a call: an HTTP call, a program run, a server started, an LLM client created or
+asked for a model. A place that only mentions an address (a link, a constant) is not a call. MCP servers are reached
+when their configured name is passed to code that uses the MCP SDK (D21's `via` rule).
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+
+from flowforge.flow.index import Func, Index, Module
+from flowforge.scan.scanner import Places
+
+CALL_TEXTS = frozenset({"calls it", "runs it", "starts it", "creates the client", "the model"})
+HTTP_METHODS = {"get": "GET", "head": "HEAD", "post": "POST", "put": "PUT", "patch": "PATCH", "delete": "DELETE",
+                "request": None, "stream": None}
+# an MCP tool whose name starts with one of these changes something; any other is read as read-only (D25)
+WRITE_VERBS = ("write", "create", "delete", "remove", "update", "set", "send", "post", "put", "insert", "upload",
+               "move", "add", "edit", "publish", "pay", "charge", "refund", "cancel", "push", "commit", "merge")
+GATHER = ("gather", "TaskGroup", "create_task", "wait", "as_completed")
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:56]
+
+
+@dataclass
+class Hit:
+    """One dependency a statement reaches: how (an HTTP method, an MCP tool) and from where."""
+
+    dep: str
+    method: str | None = None
+    tool: str | None = None
+
+
+def writes(tool: str | None) -> bool:
+    return bool(tool) and tool.lower().startswith(WRITE_VERBS)
+
+
+class Reach:
+    def __init__(self, index: Index, places: Places):
+        self.index = index
+        self.servers = {s: f"mcp-{_slug(s)}" for s in places.app_servers}
+        # (path, line) -> dependencies a call there reaches
+        self.at: dict[tuple[str, int], list[str]] = {}
+        for dep_id, items in places.by_dep.items():
+            for path, line, text in items:
+                if text in CALL_TEXTS:
+                    self.at.setdefault((path, line), []).append(dep_id)
+        # module-level names whose definition is a call place: `client = OpenAI(...)` -> its dependency
+        self.names: dict[tuple[str, str], list[str]] = {}
+        for module in index.modules.values():
+            for node in module.tree.body:
+                if isinstance(node, (ast.Assign, ast.AnnAssign)) and (deps := self._lines(module.path, node)):
+                    targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+                    for t in targets:
+                        if isinstance(t, ast.Name):
+                            self.names[(module.name, t.id)] = deps
+        self._memo: dict[str, list[Hit]] = {}
+
+    def _lines(self, path: str, node: ast.AST) -> list[str]:
+        out: list[str] = []
+        for line in range(node.lineno, (node.end_lineno or node.lineno) + 1):
+            out += [d for d in self.at.get((path, line), []) if d not in out]
+        return out
+
+    def function(self, func: Func) -> list[Hit]:
+        """Everything a function reaches, in the order its code reaches it (memoised; recursion ends)."""
+        if func.key in self._memo:
+            return self._memo[func.key]
+        self._memo[func.key] = []
+        module = self.index.modules[func.module]
+        cls = func.name.split(".")[0] if "." in func.name else None
+        hits: list[Hit] = []
+        for stmt in func.node.body:
+            for hit in self.statement(stmt, module, cls):
+                if not any(h.dep == hit.dep for h in hits):
+                    hits.append(hit)
+        self._memo[func.key] = hits
+        return hits
+
+    def statement(self, node: ast.AST, module: Module, cls: str | None = None) -> list[Hit]:
+        """What one statement (or expression) reaches: places inside it, module-level clients it uses, MCP servers
+        it names, and the in-repo functions it calls, followed through."""
+        found: list[tuple[int, int, Hit]] = []   # (line, col) keeps the code's own order
+        for sub in ast.walk(node):
+            if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)) and sub is not node:
+                continue
+            at = (getattr(sub, "lineno", 0), getattr(sub, "col_offset", 0))
+            if isinstance(sub, ast.Call):
+                for dep in self.at.get((module.path, sub.lineno), []):
+                    found.append((*at, Hit(dep, method=_method(sub))))
+                target = self.index.resolve(sub, module, cls)
+                if target is not None:
+                    callee = self.index.funcs[target]
+                    if self.index.modules[callee.module].uses_mcp:
+                        strings = [a.value for a in sub.args
+                                   if isinstance(a, ast.Constant) and isinstance(a.value, str)]
+                        server = next((self.servers[s] for s in strings if s in self.servers), None)
+                        if server:
+                            tool = next((s for s in strings if s not in self.servers), None)
+                            found.append((*at, Hit(server, tool=tool)))
+                            continue
+                    found += [(*at, h) for h in self.function(callee)]
+            elif isinstance(sub, ast.Name) and isinstance(sub.ctx, ast.Load):
+                key = (module.name, sub.id)
+                if key not in self.names and sub.id in module.aliases and "." in module.aliases[sub.id]:
+                    owner, _, name = module.aliases[sub.id].rpartition(".")   # from config import CLIENT
+                    key = (owner, name)
+                found += [(*at, Hit(d)) for d in self.names.get(key, [])]
+            elif isinstance(sub, ast.Attribute) and isinstance(sub.value, ast.Name) and sub.value.id in module.aliases:
+                dotted = module.aliases[sub.value.id]
+                owner = self.index.modules.get(dotted)
+                if owner is not None:
+                    found += [(*at, Hit(d)) for d in self.names.get((owner.name, sub.attr), [])]
+        found.sort(key=lambda f: (f[0], f[1]))
+        out: list[Hit] = []
+        for _, _, hit in found:
+            same = next((h for h in out if h.dep == hit.dep), None)
+            if same is None:
+                out.append(hit)
+            else:
+                same.method = same.method or hit.method
+                same.tool = same.tool or hit.tool
+        return out
+
+
+def _method(call: ast.Call) -> str | None:
+    if isinstance(call.func, ast.Attribute) and call.func.attr in HTTP_METHODS:
+        return HTTP_METHODS[call.func.attr]
+    return None
+
+
+def gathers(node: ast.AST) -> bool:
+    """The statement runs its calls together: asyncio.gather, a TaskGroup, create_task (D25)."""
+    for sub in ast.walk(node):
+        if isinstance(sub, ast.Call):
+            f = sub.func
+            name = f.attr if isinstance(f, ast.Attribute) else f.id if isinstance(f, ast.Name) else ""
+            if name in GATHER:
+                return True
+    return False

flowforge/flow/rewrite.py

@@ -0,0 +1,146 @@
+"""Advice written out (D27): one `asyncio.gather` in place of awaits that don't need each other, when plain code can
+write it safely, and a prompt that hands the whole advice to a coding agent. Nothing here edits a file.
+
+Safe means: the calls are in one block of one async function, each a plain `x = await …` or `await …`, and nothing
+between them reads their results or changes what they read. Calls of the same advice elsewhere are listed to move
+by hand.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import Any
+
+from flowforge.flowmap.models import Change
+from flowforge.security.logfilter import redact_code
+
+
+@dataclass
+class Call:
+    """One awaited call of a piece of advice. `stmt` and `func` are the reader's own: an `ast` statement and function
+    for Python, a `Stmt` and `curly.Func` for Dart/JS/TS (D32)."""
+
+    stmt: Any
+    func: Any
+    path: str
+    words: str          # what it does, in the code's words ("find the sight")
+    ref: str            # "planner.py:58"
+    weight: float
+    line: int = 0
+
+
+def _blocks(func: ast.AST) -> dict[int, tuple[ast.AST, list[ast.stmt]]]:
+    """Each statement's block: the node that owns it and the list it sits in."""
+    out: dict[int, tuple[ast.AST, list[ast.stmt]]] = {}
+    for node in ast.walk(func):
+        for attr in ("body", "orelse", "finalbody"):
+            stmts = getattr(node, attr, None)
+            if isinstance(stmts, list):
+                for st in stmts:
+                    if isinstance(st, ast.stmt):
+                        out[id(st)] = (node, stmts)
+        for handler in getattr(node, "handlers", []) or []:
+            for st in handler.body:
+                out[id(st)] = (handler, handler.body)
+    return out
+
+
+def _where(owner: ast.AST) -> str:
+    if isinstance(owner, ast.If):
+        return f"inside `if {redact_code(ast.unparse(owner.test))[:60]}:`"
+    if isinstance(owner, ast.AsyncWith):
+        return "inside the `async with` block"
+    if isinstance(owner, ast.With):
+        return "inside the `with` block"
+    if isinstance(owner, (ast.Try, ast.ExceptHandler)) or type(owner).__name__ == "TryStar":
+        return "inside a `try`"
+    if isinstance(owner, (ast.For, ast.AsyncFor, ast.While)):
+        return "inside a loop"
+    return "in another block"
+
+
+def _awaited(st: ast.stmt) -> tuple[str, ast.expr] | None:
+    """`x = await e` → ("x", e); `await e` → ("_", e); anything else → None."""
+    if isinstance(st, ast.Assign) and len(st.targets) == 1 and isinstance(st.value, ast.Await):
+        return ast.unparse(st.targets[0]), st.value.value
+    if isinstance(st, ast.AnnAssign) and isinstance(st.value, ast.Await) and st.simple:
+        return ast.unparse(st.target), st.value.value
+    if isinstance(st, ast.Expr) and isinstance(st.value, ast.Await):
+        return "_", st.value.value
+    return None
+
+
+def _names(node: ast.AST, ctx: type) -> set[str]:
+    return {n.id for n in ast.walk(node) if isinstance(n, ast.Name) and isinstance(n.ctx, ctx)}
+
+
+def _quoted(c: Call) -> str:
+    return f'"{c.words}" ({c.ref})'
+
+
+def change(calls: list[Call], source: str, module: ast.Module) -> Change | None:
+    """The gather for the largest group of calls that share a block, or None when it can't be written safely."""
+    func = calls[0].func
+    if not isinstance(func, ast.AsyncFunctionDef) or any(c.func is not func for c in calls):
+        return None
+    blocks = _blocks(func)
+    groups: dict[int, list[Call]] = {}
+    for c in calls:
+        if id(c.stmt) in blocks:
+            groups.setdefault(id(blocks[id(c.stmt)][1]), []).append(c)
+    if not groups:
+        return None
+    chosen = max(groups.values(), key=lambda g: (len(g), -g[0].stmt.lineno))
+    plain = [c for c in chosen if _awaited(c.stmt)]
+    if len(plain) < 2:
+        return None
+    plain.sort(key=lambda c: c.stmt.lineno)
+    body = blocks[id(plain[0].stmt)][1]
+    first, last = body.index(plain[0].stmt), body.index(plain[-1].stmt)
+    members = {id(c.stmt) for c in plain}
+    targets = set().union(*(_names(c.stmt, ast.Store) for c in plain))
+    reads = set().union(*(_names(_awaited(c.stmt)[1], ast.Load) for c in plain))
+    for st in body[first: last + 1]:
+        if id(st) not in members and (_names(st, ast.Load) & targets or _names(st, ast.Store) & reads):
+            return None   # code between them uses a result, or changes what a call reads
+
+    lines = source.splitlines()
+    indent = lines[plain[0].stmt.lineno - 1][: plain[0].stmt.col_offset]
+    names = [_awaited(c.stmt)[0] for c in plain]
+    lhs = "" if all(n == "_" for n in names) else f"{', '.join(names)} = "
+    gather = [f"{indent}{lhs}await asyncio.gather(",
+              *(f"{indent}    {ast.unparse(_awaited(c.stmt)[1])}," for c in plain), f"{indent})"]
+    end = plain[-1].stmt.end_lineno or plain[-1].stmt.lineno
+    spans = [(c.stmt.lineno, c.stmt.end_lineno or c.stmt.lineno) for c in plain]
+    after: list[str] = []
+    for n in range(plain[0].stmt.lineno, end + 1):
+        if n == spans[0][0]:
+            after += gather
+        elif not any(a <= n <= b for a, b in spans):
+            after.append(lines[n - 1])
+    weights = [c.weight for c in plain]
+    imported = any(isinstance(n, ast.Import) and any(a.name == "asyncio" for a in n.names) for n in ast.walk(module))
+    left = [c for c in calls if c not in plain]
+    return Change(
+        path=plain[0].path, first_line=plain[0].stmt.lineno,
+        before=[redact_code(x) for x in lines[plain[0].stmt.lineno - 1: end]],
+        after=[redact_code(x) for x in after], saved_ms=round(sum(weights) - max(weights), 1),
+        by_hand=[f"{_quoted(c)}: {_where(blocks[id(c.stmt)][0]) if id(c.stmt) in blocks else 'in another block'}"
+                 for c in sorted(left, key=lambda c: c.stmt.lineno)],
+        needs_import=not imported, import_text=None if imported else "import asyncio")
+
+
+def prompt(calls: list[Call], entry: str, saved_ms: float, caveat: str | None, how: str) -> str:
+    """The advice for a coding agent: where, what, why, and what not to touch. Masked; no code beyond the words."""
+    paths = sorted({c.path for c in calls})
+    lines = [f"In {', '.join(paths)}, {entry} waits for each of these calls before starting the next, "
+             "but none of them uses another's result:",
+             *(f"- line {c.ref.rsplit(':', 1)[1]}: \"{c.words}\"" for c in sorted(calls, key=lambda c: c.line)),
+             f"Make them run at the same time, {how}, so the slowest one sets the time. "
+             f"FlowForge estimates about {saved_ms / 1000:.1f} s saved."]
+    if caveat:
+        lines.append(f"Note: {caveat}")
+    lines.append("Keep the behaviour the same: the same results, the same error handling, and the same checks before "
+                 "each call. Change nothing else, and run the tests.")
+    return redact_code("\n".join(lines))[:3000]

flowforge/flowmap/__init__.py

@@ -0,0 +1 @@
+"""The flow map (D17): the Planner's picture of how an app's LLM, MCP and API calls fit together."""