feat: business/technical view toggle, translate.py, 89 new tests

Author: alexmavro

CHANGELOG.md

@@ -8,6 +8,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ### Added
 
+- Business/Technical view toggle — switch between plain-English and developer views (persisted in localStorage)
+- `translate.py` module — deterministic business-language translations for step descriptions, triggers, secrets, connection types
+- Business-mode Mermaid diagrams — 4 pre-rendered flow variants (detailed/compact × tech/business)
+- Translated UI labels: "External Service" not "API Call", "Runs daily at midnight" not "0 0 * * *", "AWS credentials" not "AWS_SECRET_ACCESS_KEY"
+- Jinja2 template globals for translation functions — eliminates duplicated label dicts
+- Per-step error isolation in business mode — one bad translation doesn't kill the whole diagram
 - `--from-json` flag for `serve` command — load pre-computed analysis from JSON file
 - Dockerfile + docker-compose for public demo deployment (pre-baked LLM summaries)
 - Compact mode for script flow diagrams — functions with >8 steps collapse to summary nodes

README.md

@@ -4,7 +4,8 @@
 [![Tests](https://github.com/Lexi-Energy/visualpy/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexi-Energy/visualpy/actions/workflows/ci.yml)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
 
-Auto-visualise Python automations for non-technical stakeholders.
+Auto-visualise Python automations so that even non-dev people can understand what is going on.
+(for example when an agentic system created scripts, or a teammember, or you vibe-coded sth. and have no idea how to give feedback now.)
 
 Drop a folder of Python scripts, get a visual breakdown of what they do, how they connect, and what they need. No execution required, no config needed.
 

tests/test_mermaid.py

@@ -537,3 +537,85 @@ def test_script_flow_with_hello_fixture(hello_script, fixtures_dir):
     assert ":::fileio" in result
     assert ":::decision" in result
     assert "subgraph" in result  # hello.py has functions
+
+
+# --- business mode ---
+
+
+def test_step_node_business_uses_translation():
+    """business=True produces translated label instead of raw description."""
+    svc = Service(name="Google Sheets", library="gspread")
+    step = Step(line_number=10, type="api_call", description="gspread.authorize()", service=svc)
+    result = _step_node(step, "test", business=True)
+    assert "Authenticates with Google Sheets" in result
+    # Should NOT have the technical prefix
+    assert "API:" not in result
+
+
+def test_step_node_business_default_false():
+    """Default business=False still produces technical output."""
+    step = Step(line_number=10, type="api_call", description="requests.get()")
+    result_default = _step_node(step, "test")
+    result_explicit = _step_node(step, "test", business=False)
+    assert result_default == result_explicit
+    assert "API: requests.get()" in result_default
+
+
+def test_script_flow_business_drops_parens():
+    """business=True subgraph labels drop the () suffix."""
+    steps = [
+        Step(line_number=1, type="api_call", description="requests.get()", function_name="fetch"),
+        Step(line_number=2, type="output", description="print()", function_name="fetch"),
+    ]
+    script = AnalyzedScript(path="test.py", steps=steps)
+    result = script_flow(script, business=True)
+    # Business: "fetch" not "fetch()"
+    assert '"fetch"' in result
+    assert '"fetch()"' not in result
+
+
+def test_script_flow_technical_keeps_parens():
+    """Default technical mode keeps () on subgraph labels."""
+    steps = [
+        Step(line_number=1, type="api_call", description="requests.get()", function_name="fetch"),
+    ]
+    script = AnalyzedScript(path="test.py", steps=steps)
+    result = script_flow(script, business=False)
+    assert '"fetch()"' in result
+
+
+def test_compact_node_business_labels():
+    """business=True uses BUSINESS_LABELS in compact summary and drops ()."""
+    steps = [
+        Step(line_number=i, type="file_io", description=f"op{i}")
+        for i in range(3)
+    ]
+    result = _compact_function_node("save_data", steps, "test", business=True)
+    assert "Read/Write File" in result  # BUSINESS_LABELS["file_io"]
+    assert "File I/O" not in result  # _TYPE_LABELS["file_io"]
+    assert "save_data" in result
+    assert "save_data()" not in result  # no parens in business mode
+
+
+def test_compact_node_technical_labels():
+    """Default technical mode uses _TYPE_LABELS and keeps ()."""
+    steps = [
+        Step(line_number=i, type="file_io", description=f"op{i}")
+        for i in range(3)
+    ]
+    result = _compact_function_node("save_data", steps, "test")
+    assert "File I/O" in result
+    assert "save_data()" in result
+
+
+def test_project_graph_business_connections():
+    """business=True translates connection edge labels."""
+    scripts = [AnalyzedScript(path="a.py"), AnalyzedScript(path="b.py")]
+    connections = [
+        ScriptConnection(source="a.py", target="b.py", type="import", detail=""),
+    ]
+    project = AnalyzedProject(path="/tmp", scripts=scripts, connections=connections)
+    result_biz = project_graph(project, business=True)
+    result_tech = project_graph(project, business=False)
+    assert '"uses"' in result_biz
+    assert '"import"' in result_tech

tests/test_server.py

@@ -480,3 +480,84 @@ async def test_script_view_with_hello_fixture(hello_script, fixtures_dir):
         resp = await ac.get(f"/script/{script.path}")
     assert resp.status_code == 200
     assert "graph TB" in resp.text
+
+
+# --- Business mode ---
+
+
+@pytest.mark.anyio
+async def test_script_view_has_four_flows():
+    """Response should contain all 4 flow variants (detailed/compact × tech/biz)."""
+    steps = [
+        Step(line_number=i, type="api_call", description=f"call{i}", function_name="big")
+        for i in range(35)
+    ]
+    script = AnalyzedScript(path="big.py", steps=steps)
+    project = AnalyzedProject(path="/tmp", scripts=[script])
+    app = create_app(project)
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        resp = await ac.get("/script/big.py")
+    assert "flow-detailed" in resp.text
+    assert "flow-compact" in resp.text
+    assert "flow-detailed-biz" in resp.text
+    assert "flow-compact-biz" in resp.text
+
+
+@pytest.mark.anyio
+async def test_overview_has_business_graph():
+    """Overview should contain both technical and business project graphs."""
+    scripts = [AnalyzedScript(path="a.py"), AnalyzedScript(path="b.py")]
+    from visualpy.models import ScriptConnection
+    connections = [ScriptConnection(source="a.py", target="b.py", type="import", detail="")]
+    project = AnalyzedProject(path="/tmp", scripts=scripts, connections=connections)
+    app = create_app(project)
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        resp = await ac.get("/")
+    # Both graph sources should be in the page
+    assert "graph-tech" in resp.text or "graph LR" in resp.text
+    assert resp.status_code == 200
+
+
+@pytest.mark.anyio
+async def test_translate_globals_registered():
+    """Jinja2 globals for translate functions should be accessible."""
+    project = AnalyzedProject(path="/tmp", scripts=[AnalyzedScript(path="a.py")])
+    app = create_app(project)
+    # Check that the globals are registered in the template env
+    from visualpy.translate import BUSINESS_LABELS
+    # Access the templates through the app
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        resp = await ac.get("/")
+    # The overview page should render without errors (proves globals work)
+    assert resp.status_code == 200
+
+
+@pytest.mark.anyio
+async def test_script_triggers_translated():
+    """Script view should contain translated trigger text."""
+    from visualpy.models import Trigger
+    script = AnalyzedScript(
+        path="job.py",
+        triggers=[Trigger(type="cli", detail="__main__ guard")],
+        steps=[Step(line_number=1, type="output", description="print()")],
+    )
+    project = AnalyzedProject(path="/tmp", scripts=[script])
+    app = create_app(project)
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        resp = await ac.get("/script/job.py")
+    assert "Can be run directly" in resp.text
+
+
+@pytest.mark.anyio
+async def test_script_secrets_translated():
+    """Script view should contain translated secret text."""
+    script = AnalyzedScript(
+        path="api.py",
+        secrets=["AWS_SECRET_ACCESS_KEY"],
+        steps=[Step(line_number=1, type="api_call", description="call()")],
+    )
+    project = AnalyzedProject(path="/tmp", scripts=[script])
+    app = create_app(project)
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as ac:
+        resp = await ac.get("/script/api.py")
+    assert "AWS credentials" in resp.text