@littledragon_wxl/drawio-style-graph 1.0.0

package/scripts/goimports.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Extract a Go module's package-import graph as autolayout graph JSON.
+
+The Go counterpart to pyimports.py / jsimports.py. Reads the module path from
+go.mod, walks the module, treats each directory of .go files as one package
+(node = its import path), and records the intra-module package imports. Stdlib
+and third-party imports are ignored. Transitive reduction is on by default so
+the diagram stays readable.
+
+  python3 goimports.py ./mymodule -o graph.json
+  python3 autolayout.py graph.json -o diagram.drawio
+
+Parsing is regex-based over `import` statements (single and block form),
+which is enough for a structural package graph. *_test.go files and vendor/
+are skipped.
+
+Usage: python3 goimports.py <module_dir> [-o graph.json] [--direction TB|LR]
+                                          [--group] [--no-reduce]
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+MODULE = re.compile(r"^module\s+(\S+)", re.MULTILINE)
+BLOCK = re.compile(r"import\s*\((.*?)\)", re.DOTALL)
+SINGLE = re.compile(r'import\s+(?:[\w.]+\s+|_\s+)?"([^"]+)"')
+QUOTED = re.compile(r'"([^"]+)"')
+
+
+def module_path(root):
+    """Read the `module` path from go.mod at the module root, or None."""
+    gomod = os.path.join(root, "go.mod")
+    if not os.path.exists(gomod):
+        return None
+    m = MODULE.search(open(gomod, encoding="utf-8", errors="ignore").read())
+    return m.group(1) if m else None
+
+
+def discover(root, modpath):
+    """Map package import path -> list of .go files (one entry per directory)."""
+    root = os.path.abspath(root)
+    pkgs = {}
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs
+                   if d not in ("vendor", "testdata") and not d.startswith(".")]
+        gofiles = [os.path.join(dirpath, f) for f in files
+                   if f.endswith(".go") and not f.endswith("_test.go")]
+        if not gofiles:
+            continue
+        rel = os.path.relpath(dirpath, root).replace(os.sep, "/")
+        ip = modpath if rel == "." else f"{modpath}/{rel}"
+        pkgs[ip] = gofiles
+    return pkgs
+
+
+def imports_of(files, modpath, pkgs):
+    """Intra-module package import paths referenced by a package's files."""
+    found = set()
+    for path in files:
+        try:
+            src = open(path, encoding="utf-8", errors="ignore").read()
+        except OSError:
+            continue
+        specs = []
+        for block in BLOCK.findall(src):
+            specs += QUOTED.findall(block)
+        specs += SINGLE.findall(src)
+        for spec in specs:
+            if (spec == modpath or spec.startswith(modpath + "/")) and spec in pkgs:
+                found.add(spec)
+    return found
+
+
+def transitive_reduce(nodes, edges):
+    """Drop edges implied by a longer path, via Graphviz `tred`."""
+    idx = {n: i for i, n in enumerate(nodes)}
+    dot = "digraph{" + "".join(f"{idx[s]}->{idx[t]};" for s, t in edges) + "}"
+    try:
+        out = subprocess.run(["tred"], input=dot, capture_output=True,
+                             text=True, check=True).stdout
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        sys.stderr.write(f"warning: tred unavailable, keeping all edges ({exc})\n")
+        return edges
+    rev = {i: n for n, i in idx.items()}
+    return [(rev[int(a)], rev[int(b)]) for a, b in re.findall(r"(\d+)\s*->\s*(\d+)", out)]
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Go import graph -> autolayout graph JSON.")
+    ap.add_argument("module", help="module directory (contains go.mod)")
+    ap.add_argument("-o", "--output", help="output JSON path (default: stdout)")
+    ap.add_argument("--direction", default="TB", choices=["TB", "LR"])
+    ap.add_argument("--group", action="store_true",
+                    help="group nodes into containers by top-level package dir")
+    ap.add_argument("--no-reduce", action="store_true",
+                    help="keep every edge (skip transitive reduction)")
+    args = ap.parse_args()
+
+    modpath = module_path(args.module)
+    if not modpath:
+        sys.exit(f"error: no go.mod with a module path found in {args.module}")
+    pkgs = discover(args.module, modpath)
+    if not pkgs:
+        sys.exit(f"error: no Go packages found under {args.module}")
+    edges = sorted({(ip, t) for ip, files in pkgs.items()
+                    for t in imports_of(files, modpath, pkgs) if t != ip})
+    raw = len(edges)
+    if not args.no_reduce:
+        edges = transitive_reduce(list(pkgs), edges)
+    # Drop the module prefix from labels for readability; ids stay full.
+    strip = modpath + "/"
+    label = lambda ip: ip[len(strip):] if ip.startswith(strip) else os.path.basename(ip)
+
+    def node(ip):
+        d = {"id": ip, "label": label(ip)}
+        if args.group:
+            rest = label(ip).split("/")
+            if len(rest) > 1:                            # nested under a sub-package
+                d["group"] = "/".join(rest[:-1])         # full sub-package path -> nested boxes
+        return d
+
+    graph = {
+        "direction": args.direction,
+        "nodes": [node(ip) for ip in pkgs],
+        "edges": [{"source": s, "target": t} for s, t in edges],
+    }
+    text = json.dumps(graph, indent=2)
+    if args.output:
+        open(args.output, "w", encoding="utf-8").write(text)
+        sys.stderr.write(f"wrote {args.output}\n")
+    else:
+        sys.stdout.write(text)
+    note = "" if args.no_reduce else f" (reduced from {raw})"
+    sys.stderr.write(f"{len(pkgs)} packages, {len(edges)} edges{note}\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/jsimports.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Extract a JS/TS project's module-import graph as autolayout graph JSON.
+
+The JavaScript/TypeScript counterpart to pyimports.py: walks a source
+directory, scans each module for static and dynamic import specifiers
+(`import`/`export ... from`, `require()`, `import()`), keeps only the
+intra-project edges (relative specifiers that resolve to a file under the
+root), and applies transitive reduction so the diagram stays readable.
+
+  python3 jsimports.py src -o graph.json
+  python3 autolayout.py graph.json -o diagram.drawio
+
+Resolution is path-based: relative specifiers are resolved against the
+importing file's directory, trying the .ts/.tsx/.js/.jsx/.mjs/.cjs extensions
+and directory index files. Bare specifiers (node_modules packages such as
+"react") are ignored. Scanning is regex-based rather than a full parser, so a
+specifier inside a comment or string literal is counted in rare cases.
+
+Usage: python3 jsimports.py <src_dir> [-o graph.json] [--direction TB|LR]
+                                       [--group] [--no-reduce]
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs")
+SPEC = re.compile(
+    r"(?:import|export)\b[^'\";]*?\bfrom\s*['\"]([^'\"]+)['\"]"  # import/export ... from "x"
+    r"|import\s*['\"]([^'\"]+)['\"]"                              # import "x" (side effect)
+    r"|require\s*\(\s*['\"]([^'\"]+)['\"]\s*\)"                   # require("x")
+    r"|import\s*\(\s*['\"]([^'\"]+)['\"]\s*\)"                    # import("x") dynamic
+)
+
+
+def modid(path, root):
+    """Module id = path relative to root, extension stripped, posix separators."""
+    rel = os.path.relpath(path, root)
+    for ext in EXTS:
+        if rel.endswith(ext):
+            rel = rel[: -len(ext)]
+            break
+    return rel.replace(os.sep, "/")
+
+
+def discover(root):
+    """Map module id -> absolute file path for every source file under root."""
+    root = os.path.abspath(root)
+    modules = {}
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d != "node_modules" and not d.startswith(".")]
+        for fn in files:
+            if fn.endswith(EXTS) and not fn.endswith(".d.ts"):
+                full = os.path.join(dirpath, fn)
+                modules[modid(full, root)] = full
+    return modules, root
+
+
+def resolve(spec, importer, root, modules):
+    """Resolve a relative specifier to a known module id, or None (external)."""
+    if not spec.startswith("."):
+        return None
+    base = os.path.normpath(os.path.join(os.path.dirname(importer), spec))
+    candidates = ([base + e for e in EXTS]
+                  + [os.path.join(base, "index" + e) for e in EXTS]
+                  + [base])
+    for cand in candidates:
+        mid = modid(cand, root)
+        if mid in modules and modules[mid] != importer:
+            return mid
+    return None
+
+
+def edges_of(mid, path, root, modules):
+    """Intra-project modules imported by module `mid`."""
+    found = set()
+    try:
+        src = open(path, encoding="utf-8", errors="ignore").read()
+    except OSError:
+        return found
+    for m in SPEC.finditer(src):
+        spec = m.group(1) or m.group(2) or m.group(3) or m.group(4)
+        target = resolve(spec, path, root, modules)
+        if target and target != mid:
+            found.add(target)
+    return found
+
+
+def transitive_reduce(nodes, edges):
+    """Drop edges implied by a longer path, via Graphviz `tred`."""
+    idx = {n: i for i, n in enumerate(nodes)}
+    dot = "digraph{" + "".join(f"{idx[s]}->{idx[t]};" for s, t in edges) + "}"
+    try:
+        out = subprocess.run(["tred"], input=dot, capture_output=True,
+                             text=True, check=True).stdout
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        sys.stderr.write(f"warning: tred unavailable, keeping all edges ({exc})\n")
+        return edges
+    rev = {i: n for n, i in idx.items()}
+    return [(rev[int(a)], rev[int(b)]) for a, b in re.findall(r"(\d+)\s*->\s*(\d+)", out)]
+
+
+def common_dir(ids):
+    """Longest shared leading path segment across module ids (e.g. 'src/')."""
+    common = []
+    for parts in zip(*[m.split("/") for m in ids]):
+        if len(set(parts)) == 1:
+            common.append(parts[0])
+        else:
+            break
+    return "/".join(common) + "/" if common else ""
+
+
+def main():
+    ap = argparse.ArgumentParser(description="JS/TS import graph -> autolayout graph JSON.")
+    ap.add_argument("src", help="source directory")
+    ap.add_argument("-o", "--output", help="output JSON path (default: stdout)")
+    ap.add_argument("--direction", default="TB", choices=["TB", "LR"])
+    ap.add_argument("--group", action="store_true",
+                    help="group nodes into containers by top-level directory")
+    ap.add_argument("--no-reduce", action="store_true",
+                    help="keep every edge (skip transitive reduction)")
+    args = ap.parse_args()
+
+    modules, root = discover(args.src)
+    if not modules:
+        sys.exit(f"error: no JS/TS modules found under {args.src}")
+    edges = sorted({(m, t) for m, p in modules.items()
+                    for t in edges_of(m, p, root, modules)})
+    raw = len(edges)
+    if not args.no_reduce:
+        edges = transitive_reduce(list(modules), edges)
+    strip = common_dir(list(modules))
+    label = lambda m: (m[len(strip):] if strip and m.startswith(strip) else m) or m
+
+    def node(m):
+        d = {"id": m, "label": label(m)}
+        if args.group:
+            rest = label(m).split("/")
+            if len(rest) > 1:                            # has a sub-directory
+                d["group"] = "/".join(rest[:-1])         # full directory path -> nested boxes
+        return d
+
+    graph = {
+        "direction": args.direction,
+        "nodes": [node(m) for m in modules],
+        "edges": [{"source": s, "target": t} for s, t in edges],
+    }
+    text = json.dumps(graph, indent=2)
+    if args.output:
+        open(args.output, "w", encoding="utf-8").write(text)
+        sys.stderr.write(f"wrote {args.output}\n")
+    else:
+        sys.stdout.write(text)
+    note = "" if args.no_reduce else f" (reduced from {raw})"
+    sys.stderr.write(f"{len(modules)} modules, {len(edges)} edges{note}\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/pyclasses.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Extract a Python project's class-inheritance graph as autolayout graph JSON.
+
+A finer-grained companion to pyimports.py: instead of module->module imports,
+it emits one node per class and an edge from each subclass to the project base
+classes it extends. With --group, classes are boxed by their module (nested by
+sub-package), so the result reads as an auto-generated class hierarchy.
+
+  python3 pyclasses.py myproject --group -o graph.json
+  python3 autolayout.py graph.json -o diagram.drawio
+
+Only inheritance is resolved (statically reliable); base classes are matched
+by name, preferring a class in the same module. External bases (object,
+Exception, third-party) are ignored. This is a *class structure* view, not a
+function-level call graph — static call resolution in Python is unreliable, so
+that is deliberately out of scope.
+
+Usage: python3 pyclasses.py <project_dir> [-o graph.json] [--direction TB|LR]
+                                          [--group] [--no-reduce]
+"""
+import argparse
+import ast
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def discover(root):
+    """Map dotted module name -> file path; qualify with the package name when
+    root is itself a package (mirrors pyimports.py)."""
+    root = os.path.abspath(root)
+    base = os.path.basename(root) if os.path.exists(os.path.join(root, "__init__.py")) else ""
+    modules = {}
+    for dirpath, _, files in os.walk(root):
+        for fn in files:
+            if not fn.endswith(".py"):
+                continue
+            rel = os.path.relpath(os.path.join(dirpath, fn), root)[:-3]
+            parts = rel.split(os.sep)
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+            parts = ([base] + parts) if base else parts
+            if parts:
+                modules[".".join(parts)] = os.path.join(dirpath, fn)
+    return modules, base
+
+
+def base_name(node):
+    """Simple name of a base-class expression (`Foo` or `pkg.Foo` -> 'Foo')."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return None
+
+
+def classes_in(module, path):
+    """Top-level classes of a module: list of (qualified_id, simple_name, [base names])."""
+    try:
+        tree = ast.parse(open(path, encoding="utf-8").read(), filename=path)
+    except SyntaxError:
+        return []
+    out = []
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            bases = [b for b in (base_name(b) for b in node.bases) if b]
+            out.append((f"{module}.{node.name}", node.name, bases))
+    return out
+
+
+def transitive_reduce(nodes, edges):
+    """Drop edges implied by a longer path, via Graphviz `tred`."""
+    idx = {n: i for i, n in enumerate(nodes)}
+    dot = "digraph{" + "".join(f"{idx[s]}->{idx[t]};" for s, t in edges) + "}"
+    try:
+        out = subprocess.run(["tred"], input=dot, capture_output=True,
+                             text=True, check=True).stdout
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        sys.stderr.write(f"warning: tred unavailable, keeping all edges ({exc})\n")
+        return edges
+    rev = {i: n for n, i in idx.items()}
+    return [(rev[int(a)], rev[int(b)]) for a, b in re.findall(r"(\d+)\s*->\s*(\d+)", out)]
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Python class-inheritance graph -> autolayout graph JSON.")
+    ap.add_argument("project", help="package or project directory")
+    ap.add_argument("-o", "--output", help="output JSON path (default: stdout)")
+    ap.add_argument("--direction", default="TB", choices=["TB", "LR"])
+    ap.add_argument("--group", action="store_true",
+                    help="box classes by their module (nested by sub-package)")
+    ap.add_argument("--no-reduce", action="store_true",
+                    help="keep every edge (skip transitive reduction)")
+    args = ap.parse_args()
+
+    modules, base = discover(args.project)
+    classes = {}                                         # qualified id -> (module, bases)
+    by_name = {}                                         # simple name -> [qualified ids]
+    for mod, path in modules.items():
+        for cid, name, bases in classes_in(mod, path):
+            classes[cid] = (mod, bases)
+            by_name.setdefault(name, []).append(cid)
+    if not classes:
+        sys.exit(f"error: no classes found under {args.project}")
+
+    def resolve(name, module):
+        cands = by_name.get(name, [])
+        same = [c for c in cands if classes[c][0] == module]
+        if same:
+            return same[0]                               # prefer a class in the same module
+        return cands[0] if len(cands) == 1 else None     # else only if unambiguous
+
+    edges = set()
+    for cid, (mod, bases) in classes.items():
+        for b in bases:
+            target = resolve(b, mod)
+            if target and target != cid:
+                edges.add((cid, target))
+    edges = sorted(edges)
+    raw = len(edges)
+    if not args.no_reduce:
+        edges = transitive_reduce(list(classes), edges)
+
+    strip = base + "." if base else ""
+    short = lambda m: m[len(strip):] if strip and m.startswith(strip) else m
+
+    def node(cid):
+        # No hard-coded colour: autolayout tints nodes by their group (module),
+        # so a grouped class hierarchy reads as coloured-by-module.
+        d = {"id": cid, "label": cid.rsplit(".", 1)[1]}
+        if args.group:
+            mod = classes[cid][0]
+            path = short(mod).replace(".", "/")          # module path -> nested boxes
+            if path:
+                d["group"] = path
+        return d
+
+    graph = {
+        "direction": args.direction,
+        "nodes": [node(cid) for cid in classes],
+        "edges": [{"source": s, "target": t} for s, t in edges],
+    }
+    text = json.dumps(graph, indent=2)
+    if args.output:
+        open(args.output, "w", encoding="utf-8").write(text)
+        sys.stderr.write(f"wrote {args.output}\n")
+    else:
+        sys.stdout.write(text)
+    note = "" if args.no_reduce else f" (reduced from {raw})"
+    sys.stderr.write(f"{len(classes)} classes, {len(edges)} inheritance edges{note}\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/pyimports.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Extract a Python project's module-import graph as autolayout graph JSON.
+
+Walks a package/project directory, parses each module with `ast`, builds the
+intra-project import edges, and (by default) applies transitive reduction so
+the diagram stays readable instead of becoming a hairball. The output feeds
+autolayout.py:
+
+  python3 pyimports.py myproject -o graph.json
+  python3 autolayout.py graph.json -o diagram.drawio
+
+Transitive reduction uses Graphviz `tred` (drops edges implied by a longer
+path); pass --no-reduce to keep every import edge. Only intra-project imports
+are kept — third-party and stdlib imports are ignored.
+
+Usage: python3 pyimports.py <project_dir> [-o graph.json] [--direction TB|LR] [--no-reduce]
+"""
+import argparse
+import ast
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def discover(root):
+    """Map dotted module name -> file path for every .py under root, plus the
+    package prefix. If root is itself a package (has __init__.py), module names
+    are qualified with its name so the project's own absolute imports resolve."""
+    root = os.path.abspath(root)
+    base = os.path.basename(root) if os.path.exists(os.path.join(root, "__init__.py")) else ""
+    modules = {}
+    for dirpath, _, files in os.walk(root):
+        for fn in files:
+            if not fn.endswith(".py"):
+                continue
+            rel = os.path.relpath(os.path.join(dirpath, fn), root)[:-3]  # strip .py
+            parts = rel.split(os.sep)
+            if parts[-1] == "__init__":
+                parts = parts[:-1]                                       # package = its dir
+            parts = ([base] + parts) if base else parts
+            if parts:
+                modules[".".join(parts)] = os.path.join(dirpath, fn)
+    return modules, base
+
+
+def resolve(name, current, modules):
+    """Resolve a dotted name to the longest known module prefix (or None)."""
+    parts = name.split(".") if name else []
+    while parts:
+        cand = ".".join(parts)
+        if cand in modules and cand != current:
+            return cand
+        parts = parts[:-1]
+    return None
+
+
+def edges_of(name, path, modules):
+    """Intra-project modules imported by `name`."""
+    pkg = name if path.endswith("__init__.py") else name.rsplit(".", 1)[0] if "." in name else ""
+    found = set()
+    try:
+        tree = ast.parse(open(path, encoding="utf-8").read(), filename=path)
+    except SyntaxError:
+        return found
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):                     # import a.b.c
+            for alias in node.names:
+                target = resolve(alias.name, name, modules)
+                if target:
+                    found.add(target)
+        elif isinstance(node, ast.ImportFrom):               # from a.b import c
+            if node.level:                                   # relative: climb level-1 packages
+                base = pkg.split(".") if pkg else []
+                base = base[: len(base) - (node.level - 1)]
+                prefix = ".".join(base)
+                mod = f"{prefix}.{node.module}" if prefix and node.module else (node.module or prefix)
+            else:
+                mod = node.module or ""
+            target = resolve(mod, name, modules)
+            if target:
+                found.add(target)
+            for alias in node.names:                         # `from pkg import submodule`
+                sub = f"{mod}.{alias.name}" if mod else alias.name
+                target = resolve(sub, name, modules)
+                if target:
+                    found.add(target)
+    return found
+
+
+def transitive_reduce(nodes, edges):
+    """Drop edges implied by a longer path, via Graphviz `tred`."""
+    idx = {n: i for i, n in enumerate(nodes)}
+    dot = "digraph{" + "".join(f"{idx[s]}->{idx[t]};" for s, t in edges) + "}"
+    try:
+        out = subprocess.run(["tred"], input=dot, capture_output=True,
+                             text=True, check=True).stdout
+    except (FileNotFoundError, subprocess.CalledProcessError) as exc:
+        sys.stderr.write(f"warning: tred unavailable, keeping all edges ({exc})\n")
+        return edges
+    rev = {i: n for n, i in idx.items()}
+    return [(rev[int(a)], rev[int(b)]) for a, b in re.findall(r"(\d+)\s*->\s*(\d+)", out)]
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Python import graph -> autolayout graph JSON.")
+    ap.add_argument("project", help="package or project directory")
+    ap.add_argument("-o", "--output", help="output JSON path (default: stdout)")
+    ap.add_argument("--direction", default="TB", choices=["TB", "LR"])
+    ap.add_argument("--group", action="store_true",
+                    help="group nodes into containers by sub-package")
+    ap.add_argument("--no-reduce", action="store_true",
+                    help="keep every edge (skip transitive reduction)")
+    args = ap.parse_args()
+
+    modules, base = discover(args.project)
+    if not modules:
+        sys.exit(f"error: no .py modules found under {args.project}")
+    edges = sorted({(name, t) for name, path in modules.items()
+                    for t in edges_of(name, path, modules)})
+    raw = len(edges)
+    if not args.no_reduce:
+        edges = transitive_reduce(list(modules), edges)
+    # Drop the shared package prefix from labels for readability; ids stay full.
+    strip = base + "." if base else ""
+    label = lambda m: m[len(strip):] if strip and m.startswith(strip) else m
+
+    def node(m):
+        d = {"id": m, "label": label(m)}
+        if args.group:
+            rest = label(m).split(".")
+            if len(rest) > 1:                            # nested under a sub-package
+                d["group"] = "/".join(rest[:-1])         # full sub-package path -> nested boxes
+        return d
+
+    graph = {
+        "direction": args.direction,
+        "nodes": [node(m) for m in modules],
+        "edges": [{"source": s, "target": t} for s, t in edges],
+    }
+    text = json.dumps(graph, indent=2)
+    if args.output:
+        open(args.output, "w", encoding="utf-8").write(text)
+        sys.stderr.write(f"wrote {args.output}\n")
+    else:
+        sys.stdout.write(text)
+    note = "" if args.no_reduce else f" (reduced from {raw})"
+    sys.stderr.write(f"{len(modules)} modules, {len(edges)} edges{note}\n")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/repair_png.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""Repair truncated IEND chunk in draw.io -e PNG exports (issue #8).
+
+draw.io's CLI emits -e PNGs with the 4-byte IEND length field but missing
+the 8 bytes of "IEND" type + CRC. Strict PNG decoders and vision APIs
+(Anthropic included) reject the file with 400 "Could not process image".
+SVG/PDF are unaffected.
+
+Usage: python3 repair_png.py <path/to/diagram.drawio.png>
+
+Idempotent: the endswith(IEND) guard makes this a no-op once draw.io
+fixes the bug upstream, so it's safe to run unconditionally after every
+-e PNG export.
+"""
+import sys
+
+IEND = b"\x00\x00\x00\x00IEND\xaeB`\x82"
+
+
+def repair(path: str) -> bool:
+    with open(path, "rb") as f:
+        data = f.read()
+    if data.endswith(IEND):
+        return False
+    if data.endswith(b"\x00\x00\x00\x00"):
+        data = data[:-4]
+    with open(path, "wb") as f:
+        f.write(data + IEND)
+    return True
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("usage: repair_png.py <path>", file=sys.stderr)
+        sys.exit(2)
+    if repair(sys.argv[1]):
+        print(f"repaired {sys.argv[1]}")