baghban 0.1.0__py3-none-any.whl

baghban/__init__.py

@@ -0,0 +1,23 @@
+"""baghban (باغبان, bağban: gardener) — tend Bonsai workflows from Python.
+
+Check, draw and compare Bonsai (bonsai-rx.org) workflow files on any
+machine, macOS included, without Windows or .NET. Standard library only.
+
+    import baghban
+    doc = baghban.load("rig/foraging.bonsai")
+    print(baghban.check(doc).summary())
+"""
+
+__version__ = "0.1.0"
+
+from .model import Document, Node, Workflow, TypeRef, Include, WorkflowLoadError, load, loads
+from .checks import Finding, Report, check, FINDINGS
+from .diff import diff, WorkflowDiff
+from .info import dependencies, parameters, fingerprint, manifest_fields
+from .render import outline, mermaid, dot, html
+
+__all__ = [
+    "Document", "Node", "Workflow", "TypeRef", "Include", "WorkflowLoadError", "load", "loads",
+    "Finding", "Report", "check", "FINDINGS", "diff", "WorkflowDiff", "dependencies",
+    "parameters", "fingerprint", "manifest_fields", "outline", "mermaid", "dot", "html",
+]

baghban/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

baghban/checks.py

@@ -0,0 +1,384 @@
+"""Static checks: problems a Bonsai workflow has before it is ever run.
+
+Each check reports a problem only when the XML is enough to be sure of it.
+When it is not (an include that cannot be opened, a file name computed from
+data at run time), the check stays quiet and says what it could not see in
+``Report.skipped``, instead of guessing.
+
+Behaviour that the checks rely on, verified in the Bonsai source:
+
+* ``CsvWriter`` and ``FileSink`` (Bonsai.System/IO) open their file when they
+  are *subscribed*, check ``File.Exists(path) && !Overwrite`` (and ``!Append``
+  for CsvWriter), then create it. ``PathSuffix`` is ``None``, ``FileCount`` or
+  ``Timestamp`` (ISO 8601 with 100 ns resolution).
+* ``SelectMany``, ``CreateObservable`` and ``WindowWorkflow`` subscribe their
+  nested workflow once per input element, so a writer inside one is opened
+  once per element: typically once per trial.
+* Declaring two subjects with the same name in one build context raises
+  "A variable with the specified name already exists" (BuildContext.cs).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .model import Document, Node, Workflow
+
+SEVERITIES = ("error", "warning", "info")
+PIPE_PREFIX = "\\\\.\\pipe\\"
+
+# code -> (severity, one-line description); the README findings table mirrors this.
+FINDINGS = {
+    "SILENT_OVERWRITE": ("error", "a writer replaces data from an earlier run or trial without warning"),
+    "FAILS_ON_REPEAT": ("error", "a writer inside a per-trial loop raises 'file already exists' on the second trial"),
+    "DUPLICATE_OUTPUT": ("error", "two writers write to the same file"),
+    "DANGLING_SUBJECT": ("error", "a SubscribeSubject/MulticastSubject names a subject that is not declared in scope"),
+    "DUPLICATE_SUBJECT": ("error", "two subjects with the same name are declared in one scope"),
+    "MISSING_INCLUDE": ("error", "an IncludeWorkflow points at a file that does not exist"),
+    "RECURSIVE_INCLUDE": ("error", "workflows include each other in a cycle"),
+    "INVALID_INCLUDE": ("error", "an included file is not a readable workflow"),
+    "DISABLED_WRITER": ("warning", "a writer is disabled, so nothing is recorded to its file"),
+    "APPENDS_ACROSS_RUNS": ("info", "every run appends to the same file"),
+    "UNUSED_SUBJECT": ("info", "a subject is declared but nothing subscribes to it"),
+}
+
+
+@dataclass
+class Finding:
+    code: str
+    severity: str
+    message: str
+    location: str
+    file: Optional[str] = None
+    node: tuple = ()
+    hint: str = ""
+
+    def to_dict(self) -> dict:
+        return {"code": self.code, "severity": self.severity, "message": self.message,
+                "location": self.location, "file": self.file, "node": list(self.node),
+                "hint": self.hint}
+
+
+@dataclass
+class Report:
+    path: Optional[str]
+    findings: list = field(default_factory=list)
+    skipped: list = field(default_factory=list)
+    n_nodes: int = 0
+
+    def by_severity(self, severity: str) -> list:
+        return [f for f in self.findings if f.severity == severity]
+
+    @property
+    def errors(self) -> list:
+        return self.by_severity("error")
+
+    @property
+    def warnings(self) -> list:
+        return self.by_severity("warning")
+
+    def codes(self) -> list:
+        return [f.code for f in self.findings]
+
+    def exit_code(self, strict: bool = False) -> int:
+        if self.errors or (strict and self.warnings):
+            return 1
+        return 0
+
+    def summary(self, show_info: bool = True) -> str:
+        lines = []
+        for f in self.findings:
+            if f.severity == "info" and not show_info:
+                continue
+            lines.append(f"[{f.severity}] {f.code}  {f.location}")
+            where = f"   in {f.file}" if f.file and f.file != self.path else ""
+            if where:
+                lines.append(where)
+            for text in _wrap(f.message):
+                lines.append(f"    {text}")
+            if f.hint:
+                for text in _wrap("fix: " + f.hint):
+                    lines.append(f"    {text}")
+            lines.append("")
+        counts = [f"{len(self.by_severity(s))} {s}{'s' if len(self.by_severity(s)) != 1 else ''}"
+                  for s in SEVERITIES]
+        if not self.findings:
+            lines.append(f"No findings in {self.n_nodes} nodes.")
+        else:
+            lines.append(", ".join(counts) + f" in {self.n_nodes} nodes.")
+        for note in self.skipped:
+            lines.append(f"not checked: {note}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {"path": self.path, "nodes": self.n_nodes,
+                "findings": [f.to_dict() for f in self.findings],
+                "skipped": list(self.skipped)}
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+
+def _wrap(text: str, width: int = 88) -> list:
+    import textwrap
+    return textwrap.wrap(text, width) or [""]
+
+
+def _bool(value: Optional[str]) -> bool:
+    return (value or "").strip().lower() == "true"
+
+
+def _finding(code: str, node: Node, message: str, hint: str = "",
+             severity: Optional[str] = None) -> Finding:
+    return Finding(code=code, severity=severity or FINDINGS[code][0], message=message,
+                   location=node.location(), file=str(node.file) if node.file else None,
+                   node=node.id, hint=hint)
+
+
+# --------------------------------------------------------------------------- includes
+
+def check_includes(doc: Document, report: Report) -> None:
+    for node in doc.walk():
+        if not node.is_include or node.include is None or node.is_effectively_disabled():
+            continue
+        inc = node.include
+        if inc.status == "missing":
+            report.findings.append(_finding(
+                "MISSING_INCLUDE", node,
+                f"IncludeWorkflow Path='{inc.path}' cannot be found ({inc.note}). "
+                "Bonsai will fail to build the workflow.",
+                hint="Include paths are resolved relative to the folder of the top-level "
+                     "workflow (the editor's working directory), also for nested includes."))
+        elif inc.status == "recursive":
+            report.findings.append(_finding(
+                "RECURSIVE_INCLUDE", node, f"{inc.note}. Bonsai cannot build a workflow "
+                "that includes itself."))
+        elif inc.status == "invalid":
+            report.findings.append(_finding("INVALID_INCLUDE", node, inc.note))
+        elif inc.status == "unresolved":
+            report.skipped.append(f"{node.location()}: {inc.note}")
+
+
+# --------------------------------------------------------------------------- subjects
+
+def _enabled(node: Node) -> bool:
+    return not node.is_effectively_disabled()
+
+
+def check_subjects(doc: Document, report: Report) -> None:
+    declared: dict[int, dict[str, list]] = {}
+    scopes: dict[int, Workflow] = {}
+    opaque: set = set()
+
+    for wf in doc.workflow.workflows():
+        scope = wf.scope()
+        scopes[id(scope)] = scope
+        declared.setdefault(id(scope), {})
+        for node in wf.nodes:
+            if not _enabled(node):
+                continue
+            if node.is_subject_declaration and node.name:
+                declared[id(scope)].setdefault(node.name, []).append(node)
+            if node.is_include and node.include is not None and node.include.status != "ok":
+                opaque.add(id(scope))
+
+    def chain(scope: Workflow):
+        s: Optional[Workflow] = scope
+        while s is not None:
+            yield s
+            s = s.parent_scope()
+
+    # scopes that contain (at any depth) something baghban could not read
+    opaque_within: set = set()
+    for sid in opaque:
+        for s in chain(scopes[sid]):
+            opaque_within.add(id(s))
+
+    for sid, names in declared.items():
+        for name, nodes in names.items():
+            if len(nodes) > 1:
+                first = nodes[0]
+                for dup in nodes[1:]:
+                    report.findings.append(_finding(
+                        "DUPLICATE_SUBJECT", dup,
+                        f"Subject '{name}' is already declared in this scope by "
+                        f"{first.location()}. Bonsai refuses to build the workflow. "
+                        "Groups and included workflows share their parent's scope, so "
+                        "declarations inside them count as declarations next to them.",
+                        hint="Rename one of them, or move one inside a nested workflow such as "
+                             "SelectMany if it is meant to be local."))
+
+    used: set = set()
+    skipped_names: set = set()
+    for node in doc.walk():
+        if not node.is_subject_use or not _enabled(node):
+            continue
+        scope = node.parent.scope()
+        if not node.name:
+            report.findings.append(_finding(
+                "DANGLING_SUBJECT", node, f"{node.type.name} has no subject Name."))
+            continue
+        target = None
+        blind = False
+        for s in chain(scope):
+            if id(s) in opaque:
+                blind = True
+            hits = declared.get(id(s), {}).get(node.name)
+            if hits:
+                target = hits[0]
+                break
+        if target is not None:
+            used.add(id(target))
+        elif blind:
+            key = (node.name, id(scope))
+            if key not in skipped_names:
+                skipped_names.add(key)
+                report.skipped.append(f"subject '{node.name}' used at {node.location()} may be "
+                                      "declared in an include that could not be read")
+        else:
+            hidden = [d for names in declared.values() for d in names.get(node.name, [])]
+            if hidden:
+                why = (f" A subject with this name is declared at {hidden[0].location()}, but "
+                       "that is inside a nested workflow, whose declarations are not visible "
+                       "outside it (groups are the exception).")
+                hint = "Move the declaration out of the nested workflow, or into a group."
+            else:
+                why = ""
+                hint = _near_miss(node.name, declared)
+            report.findings.append(_finding(
+                "DANGLING_SUBJECT", node,
+                f"No subject named '{node.name}' is declared in this scope or any enclosing "
+                f"one, so Bonsai will fail to build the workflow.{why}", hint=hint))
+
+    for sid, names in declared.items():
+        if sid in opaque_within:
+            continue
+        for name, nodes in names.items():
+            if len(nodes) > 1:
+                continue  # already reported as DUPLICATE_SUBJECT
+            for decl in nodes:
+                if id(decl) not in used and not decl.type.is_core("ResourceSubject"):
+                    report.findings.append(_finding(
+                        "UNUSED_SUBJECT", decl,
+                        f"Subject '{name}' is declared but nothing subscribes to it."))
+
+
+def _near_miss(name: str, declared: dict) -> str:
+    import difflib
+    names = {n for scope in declared.values() for n in scope}
+    close = difflib.get_close_matches(name, sorted(names), n=1, cutoff=0.75)
+    return f"Did you mean '{close[0]}'?" if close else ""
+
+
+# --------------------------------------------------------------------------- writers
+
+def _loop_name(node: Node) -> str:
+    return f"{node.type.name}" + (f" '{node.name}'" if node.name else "")
+
+
+def check_writers(doc: Document, report: Report) -> None:
+    outputs: dict[str, list] = {}
+    for node in doc.walk():
+        if not node.is_writer:
+            continue
+        prop = node.filename_property
+        fname = node.properties.get(prop, "") or ""
+
+        if node.is_effectively_disabled():
+            why = "is disabled" if node.disabled else "sits inside a disabled node"
+            report.findings.append(_finding(
+                "DISABLED_WRITER", node,
+                f"This {node.type.name} {why}, so nothing will be written to "
+                f"'{fname or '(no file name)'}'. Disabling a writer while debugging and "
+                "forgetting to re-enable it loses whole sessions without an error.",
+                hint="Re-enable it, or delete it if the data is not needed."))
+            continue
+
+        if prop in node.mapped():
+            report.skipped.append(f"{node.location()}: {prop} is assigned from data at "
+                                  "run time")
+            continue
+        if not fname or fname.startswith(PIPE_PREFIX):
+            continue
+
+        suffix = (node.properties.get("Suffix") or "None").strip()
+        overwrite = _bool(node.properties.get("Overwrite"))
+        append = _bool(node.properties.get("Append"))
+        externalized = prop in node.externalized()
+        loop = node.repeating_container()
+
+        if suffix == "None":
+            outputs.setdefault(_normalise(fname), []).append(node)
+            if append:
+                header = (" With IncludeHeader=True the header row is written again in the "
+                          "middle of the file each time." if _bool(node.properties.get("IncludeHeader")) else "")
+                report.findings.append(_finding(
+                    "APPENDS_ACROSS_RUNS", node,
+                    f"Append=True with Suffix=None: every run appends to '{fname}', so rows "
+                    f"from different sessions accumulate in one file.{header}",
+                    hint="Fine if intended; otherwise use Suffix=Timestamp."))
+            elif overwrite and loop is not None:
+                report.findings.append(_finding(
+                    "SILENT_OVERWRITE", node,
+                    f"Overwrite=True with Suffix=None inside {_loop_name(loop)}: the writer is "
+                    f"opened again for every element (e.g. every trial), and each time it "
+                    f"replaces '{fname}'. Only the last element's data survives the session.",
+                    hint="Use Suffix=Timestamp or FileCount to keep one file per element, or "
+                         "move the writer after the SelectMany to collect all elements in one "
+                         "file."))
+            elif overwrite:
+                severity = "warning" if externalized else "error"
+                extra = (f" {prop} is externalized, so this is only safe if the launcher sets a "
+                         "new value on every run." if externalized else "")
+                report.findings.append(_finding(
+                    "SILENT_OVERWRITE", node,
+                    f"Overwrite=True with Suffix=None: each run replaces '{fname}' from the "
+                    f"previous session, without an error.{extra}",
+                    hint="Use Suffix=Timestamp (one file per run), or Overwrite=False so a "
+                         "second run stops instead of destroying data.",
+                    severity=severity))
+            elif loop is not None:
+                report.findings.append(_finding(
+                    "FAILS_ON_REPEAT", node,
+                    f"Suffix=None and Overwrite=False inside {_loop_name(loop)}: the first "
+                    f"element creates '{fname}', the second finds it already exists and "
+                    "raises an IOException, which terminates the workflow mid-session.",
+                    hint="Use Suffix=Timestamp or FileCount, or move the writer after the "
+                         "SelectMany."))
+
+    for key, nodes in outputs.items():
+        if len(nodes) < 2:
+            continue
+        others = "; ".join(n.location() for n in nodes[:-1])
+        for dup in nodes[1:]:
+            report.findings.append(_finding(
+                "DUPLICATE_OUTPUT", dup,
+                f"Another writer also writes '{dup.properties[dup.filename_property]}' "
+                f"({others}). Two writers cannot hold the same file: one of them fails, or "
+                "they overwrite each other. This is common when a module containing a "
+                "writer is included twice without giving each copy its own file name.",
+                hint="Give each writer its own file name; for included modules, externalize "
+                     "FileName and set it on each IncludeWorkflow."))
+
+
+def _normalise(fname: str) -> str:
+    # Bonsai rigs run on Windows, where paths are case-insensitive.
+    return fname.replace("\\", "/").strip().casefold()
+
+
+# --------------------------------------------------------------------------- entry point
+
+CHECKS = (check_includes, check_subjects, check_writers)
+
+
+def check(doc: Document) -> Report:
+    """Run every check on a loaded document."""
+    report = Report(path=str(doc.path) if doc.path else None,
+                    n_nodes=sum(1 for _ in doc.walk()))
+    for fn in CHECKS:
+        fn(doc, report)
+    order = {s: i for i, s in enumerate(SEVERITIES)}
+    report.findings.sort(key=lambda f: (order[f.severity], f.node))
+    return report

baghban/cli.py

@@ -0,0 +1,211 @@
+"""baghban command line.
+
+    baghban check  WORKFLOW|DIR ...   problems found before the rig runs (exit 1 on errors)
+    baghban show   WORKFLOW           the workflow as a tree
+    baghban render WORKFLOW -f html   draw it (html | mermaid | dot)
+    baghban diff   A B                what changed, by meaning rather than by line
+    baghban deps   WORKFLOW           assemblies/packages and includes it needs
+    baghban params WORKFLOW           externalized properties and their values
+    baghban fingerprint WORKFLOW      content hash, stable across re-saves
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .checks import check
+from .diff import diff
+from .info import (dependencies, fingerprint, format_dependencies, format_parameters,
+                   manifest_fields, parameters)
+from .model import WorkflowLoadError, load
+from .render import dot, html, mermaid, outline
+
+
+def _resource_roots(values) -> dict:
+    roots = {}
+    for item in values or []:
+        name, sep, folder = item.partition("=")
+        if not sep:
+            raise SystemExit(f"--resource-root expects ASSEMBLY=DIR, got '{item}'")
+        roots[name] = folder
+    return roots
+
+
+def _collect(paths) -> list:
+    files = []
+    for p in map(Path, paths):
+        if p.is_dir():
+            for f in sorted(p.rglob("*.bonsai")):
+                if any(part.startswith(".") for part in f.relative_to(p).parts[:-1]):
+                    continue  # skip .bonsai environment folders and hidden dirs
+                files.append(f)
+        else:
+            files.append(p)
+    return files
+
+
+def _load(path, args):
+    try:
+        return load(path, resource_roots=_resource_roots(getattr(args, "resource_root", None)))
+    except (WorkflowLoadError, OSError) as exc:
+        raise SystemExit(f"baghban: {exc}")
+
+
+def cmd_check(args) -> int:
+    files = _collect(args.paths)
+    if not files:
+        print("baghban: no .bonsai files found", file=sys.stderr)
+        return 2
+    docs, failures = [], []
+    for f in files:
+        try:
+            docs.append(load(f, resource_roots=_resource_roots(args.resource_root)))
+        except (WorkflowLoadError, OSError) as exc:
+            failures.append(str(exc))
+
+    # A file that another checked file includes is checked through its includer,
+    # where the subjects and parameters it relies on are defined.
+    included = {p for d in docs for p in d.included_files}
+    roots = [d for d in docs if d.path.resolve() not in included]
+    via_includer = len(docs) - len(roots)
+
+    reports = [check(d) for d in roots]
+    code = max([r.exit_code(args.strict) for r in reports] + [1 if failures else 0])
+
+    if args.json:
+        print(json.dumps({"reports": [r.to_dict() for r in reports], "unreadable": failures},
+                         indent=2))
+        return code
+
+    for i, r in enumerate(reports):
+        if len(reports) > 1:
+            print(("\n" if i else "") + f"== {r.path}")
+        print(r.summary(show_info=not args.no_info))
+    for msg in failures:
+        print(f"unreadable: {msg}")
+    if via_includer:
+        print(f"\n{via_includer} file(s) checked through the workflows that include them.")
+    return code
+
+
+def cmd_show(args) -> int:
+    print(outline(_load(args.workflow, args)))
+    return 0
+
+
+def cmd_render(args) -> int:
+    doc = _load(args.workflow, args)
+    fmt = args.format
+    if fmt == "html":
+        text = html(doc, check(doc))
+    elif fmt == "dot":
+        text = dot(doc, check(doc).findings)
+    else:
+        text = mermaid(doc, check(doc).findings)
+    out = args.output
+    if out is None and fmt == "html":
+        out = Path(args.workflow).with_suffix(".html").name
+    if out:
+        Path(out).write_text(text, encoding="utf-8")
+        print(f"wrote {out}")
+    else:
+        print(text)
+    return 0
+
+
+def cmd_diff(args) -> int:
+    result = diff(_load(args.a, args), _load(args.b, args))
+    print(json.dumps(result.to_dict(), indent=2, default=str) if args.json else result.summary())
+    return 0 if result.identical else 1
+
+
+def cmd_deps(args) -> int:
+    deps = dependencies(_load(args.workflow, args))
+    print(json.dumps(deps, indent=2) if args.json else format_dependencies(deps))
+    return 0
+
+
+def cmd_params(args) -> int:
+    params = parameters(_load(args.workflow, args))
+    print(json.dumps(params, indent=2) if args.json else format_parameters(params))
+    return 0
+
+
+def cmd_fingerprint(args) -> int:
+    doc = _load(args.workflow, args)
+    if args.fields:
+        print(json.dumps(manifest_fields(doc), indent=2))
+    else:
+        print(f"{fingerprint(doc)}  {args.workflow}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="baghban",
+        description="Check, draw and compare Bonsai workflows without Windows or .NET.")
+    p.add_argument("--version", action="version", version=f"baghban {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def with_roots(sp):
+        sp.add_argument("--resource-root", action="append", metavar="ASSEMBLY=DIR",
+                        help="folder holding the source of an assembly, to follow "
+                             "embedded-resource includes (repeatable)")
+        return sp
+
+    c = with_roots(sub.add_parser("check", help="find problems before the rig runs"))
+    c.add_argument("paths", nargs="+", help=".bonsai files or folders")
+    c.add_argument("--json", action="store_true")
+    c.add_argument("--strict", action="store_true", help="exit 1 on warnings too")
+    c.add_argument("--no-info", action="store_true", help="hide info-level findings")
+    c.set_defaults(func=cmd_check)
+
+    s = with_roots(sub.add_parser("show", help="print the workflow as a tree"))
+    s.add_argument("workflow")
+    s.set_defaults(func=cmd_show)
+
+    r = with_roots(sub.add_parser("render", help="draw the workflow"))
+    r.add_argument("workflow")
+    r.add_argument("-f", "--format", choices=("html", "mermaid", "dot"), default="html")
+    r.add_argument("-o", "--output", help="output file (html defaults to WORKFLOW.html)")
+    r.set_defaults(func=cmd_render)
+
+    d = with_roots(sub.add_parser("diff", help="semantic diff of two workflows"))
+    d.add_argument("a")
+    d.add_argument("b")
+    d.add_argument("--json", action="store_true")
+    d.set_defaults(func=cmd_diff)
+
+    dp = with_roots(sub.add_parser("deps", help="assemblies and includes the workflow needs"))
+    dp.add_argument("workflow")
+    dp.add_argument("--json", action="store_true")
+    dp.set_defaults(func=cmd_deps)
+
+    pa = with_roots(sub.add_parser("params", help="externalized properties and values"))
+    pa.add_argument("workflow")
+    pa.add_argument("--json", action="store_true")
+    pa.set_defaults(func=cmd_params)
+
+    f = with_roots(sub.add_parser("fingerprint", help="content hash stable across re-saves"))
+    f.add_argument("workflow")
+    f.add_argument("--fields", action="store_true",
+                   help="print provenance fields (for daftar) instead of the hash")
+    f.set_defaults(func=cmd_fingerprint)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:  # e.g. `baghban diff a b | head`
+        sys.stderr.close()
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())