vibepiler 0.4.12__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. vibepiler/__init__.py +26 -0
  2. vibepiler/backend/__init__.py +9 -0
  3. vibepiler/backend/common.py +116 -0
  4. vibepiler/backend/dot.py +73 -0
  5. vibepiler/backend/html.py +75 -0
  6. vibepiler/backend/json_out.py +30 -0
  7. vibepiler/backend/markdown.py +170 -0
  8. vibepiler/backend/mermaid.py +41 -0
  9. vibepiler/backend/terminal.py +197 -0
  10. vibepiler/backend/viewer.html +1416 -0
  11. vibepiler/cli.py +425 -0
  12. vibepiler/compiler.py +278 -0
  13. vibepiler/config.py +79 -0
  14. vibepiler/frontend/__init__.py +15 -0
  15. vibepiler/frontend/facts.py +139 -0
  16. vibepiler/frontend/flow.py +96 -0
  17. vibepiler/frontend/languages/__init__.py +35 -0
  18. vibepiler/frontend/languages/base.py +227 -0
  19. vibepiler/frontend/languages/javascript.py +960 -0
  20. vibepiler/frontend/languages/javascript_flow.py +276 -0
  21. vibepiler/frontend/languages/js_project.py +269 -0
  22. vibepiler/frontend/languages/python.py +945 -0
  23. vibepiler/frontend/languages/python_flow.py +246 -0
  24. vibepiler/frontend/loader.py +252 -0
  25. vibepiler/frontend/parser.py +45 -0
  26. vibepiler/ir/__init__.py +6 -0
  27. vibepiler/ir/builder.py +944 -0
  28. vibepiler/ir/graph.py +170 -0
  29. vibepiler/ir/model.py +110 -0
  30. vibepiler/ir/program.py +42 -0
  31. vibepiler/passes/__init__.py +5 -0
  32. vibepiler/passes/abstraction.py +221 -0
  33. vibepiler/passes/astutil.py +38 -0
  34. vibepiler/passes/base.py +57 -0
  35. vibepiler/passes/bloat.py +255 -0
  36. vibepiler/passes/bloat_score.py +346 -0
  37. vibepiler/passes/cognitive.py +95 -0
  38. vibepiler/passes/complexity.py +104 -0
  39. vibepiler/passes/concepts.py +59 -0
  40. vibepiler/passes/cycles.py +56 -0
  41. vibepiler/passes/dataflow.py +211 -0
  42. vibepiler/passes/dead_code.py +126 -0
  43. vibepiler/passes/diagnostic.py +53 -0
  44. vibepiler/passes/duplicates.py +118 -0
  45. vibepiler/passes/entry_points.py +158 -0
  46. vibepiler/passes/graphalgo.py +29 -0
  47. vibepiler/passes/halstead.py +48 -0
  48. vibepiler/passes/hotspots.py +70 -0
  49. vibepiler/passes/liveness.py +279 -0
  50. vibepiler/passes/manifests.py +232 -0
  51. vibepiler/passes/measures.py +107 -0
  52. vibepiler/passes/metric.py +202 -0
  53. vibepiler/passes/registry.py +152 -0
  54. vibepiler/passes/responsibilities.py +91 -0
  55. vibepiler/passes/scope.py +70 -0
  56. vibepiler/passes/semantic_duplicates.py +82 -0
  57. vibepiler/passes/unused_imports.py +58 -0
  58. vibepiler/passes/wrappers.py +117 -0
  59. vibepiler/progress.py +66 -0
  60. vibepiler/remote.py +80 -0
  61. vibepiler/semantic/__init__.py +1 -0
  62. vibepiler/semantic/concepts.py +230 -0
  63. vibepiler/semantic/embed.py +504 -0
  64. vibepiler/semantic/similar.py +34 -0
  65. vibepiler-0.4.12.dist-info/METADATA +651 -0
  66. vibepiler-0.4.12.dist-info/RECORD +69 -0
  67. vibepiler-0.4.12.dist-info/WHEEL +4 -0
  68. vibepiler-0.4.12.dist-info/entry_points.txt +2 -0
  69. vibepiler-0.4.12.dist-info/licenses/LICENSE +21 -0
vibepiler/__init__.py ADDED
@@ -0,0 +1,26 @@
1
+ """Vibepiler: a compiler for vibe-coded software."""
2
+
3
+ import os
4
+ from typing import TYPE_CHECKING
5
+
6
+ from loguru import logger
7
+
8
+ __version__ = "0.4.12"
9
+
10
+ if not os.environ.get("VIBEPILER_DEBUG"):
11
+ logger.disable("vibepiler") # a library is quiet until asked: loguru.logger.enable("vibepiler"), the CLI, or VIBEPILER_DEBUG=1
12
+
13
+ if TYPE_CHECKING:
14
+ from vibepiler.compiler import Compiler, compile # noqa: F401 - `vibepiler.compile(source, ...)`, `vibepiler.Compiler(source)`
15
+
16
+
17
+ def __getattr__(name: str): # noqa: ANN202 - PEP 562: `vibepiler.compile` without importing the driver at package import
18
+ if name in ("compile", "Compiler"):
19
+ from vibepiler import compiler
20
+
21
+ return getattr(compiler, name)
22
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
23
+
24
+
25
+ def __dir__() -> list[str]:
26
+ return sorted([*globals(), "compile", "Compiler"])
@@ -0,0 +1,9 @@
1
+ """Backends: turn the program graph + diagnostics into files people and tools can read."""
2
+
3
+ from vibepiler.backend.dot import emit_dot
4
+ from vibepiler.backend.html import emit_html
5
+ from vibepiler.backend.json_out import emit_json
6
+ from vibepiler.backend.markdown import emit_markdown
7
+ from vibepiler.backend.mermaid import emit_mermaid
8
+
9
+ __all__ = ["emit_dot", "emit_html", "emit_json", "emit_markdown", "emit_mermaid"]
@@ -0,0 +1,116 @@
1
+ """Shared presentation helpers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import defaultdict
6
+
7
+ from vibepiler.ir.model import EdgeKind, Node, NodeKind
8
+ from vibepiler.ir.program import Program
9
+ from vibepiler.passes.diagnostic import Diagnostic, Severity
10
+
11
+ KIND_COLORS = {
12
+ NodeKind.MODULE: "#4C78A8",
13
+ NodeKind.PACKAGE: "#9D9D9D",
14
+ NodeKind.CLASS: "#F58518",
15
+ NodeKind.FUNCTION: "#54A24B",
16
+ NodeKind.METHOD: "#72B7B2",
17
+ NodeKind.VARIABLE: "#B279A2",
18
+ }
19
+ EDGE_STYLES = {
20
+ EdgeKind.IMPORTS: ("#4C78A8", "solid"),
21
+ EdgeKind.CALLS: ("#54A24B", "solid"),
22
+ EdgeKind.REFERENCES: ("#B279A2", "dashed"),
23
+ EdgeKind.INHERITS: ("#F58518", "bold"),
24
+ EdgeKind.CONTAINS: ("#CCCCCC", "dotted"),
25
+ }
26
+ SEVERITY_ORDER = [Severity.ERROR, Severity.WARNING, Severity.INFO]
27
+
28
+
29
+ def diagnostics_by_node(program: Program) -> dict[str, list[Diagnostic]]:
30
+ out: dict[str, list[Diagnostic]] = defaultdict(list)
31
+ for d in program.diagnostics:
32
+ if d.node_id:
33
+ out[d.node_id].append(d)
34
+ return out
35
+
36
+
37
+ def worst_severity(diags: list[Diagnostic]) -> Severity | None:
38
+ return max((d.severity for d in diags), default=None)
39
+
40
+
41
+ def cycle_edges(program: Program) -> set[tuple[str, str]]:
42
+ g = program.graph
43
+ pairs: set[tuple[str, str]] = set()
44
+ for cyc in program.metrics.get("cycles", {}).get("cycles", []):
45
+ members = {f"mod:{f}" for f in cyc["modules"]}
46
+ for e in g.edges(EdgeKind.IMPORTS):
47
+ if e.src in members and e.dst in members:
48
+ pairs.add((e.src, e.dst))
49
+ return pairs
50
+
51
+
52
+ def short_label(n: Node) -> str:
53
+ if n.kind is NodeKind.MODULE:
54
+ return n.name
55
+ if n.kind is NodeKind.PACKAGE:
56
+ return f"[{n.name}]"
57
+ return n.qualname
58
+
59
+
60
+ def size_parts(b: dict) -> dict[str, str]:
61
+ """The pieces of the `size` line, plain text; the terminal and markdown backends only add their markup."""
62
+ conf = ", ".join(f"{k} {v:.0f}" for k, v in b.get("waste_by_confidence", {}).items() if k != "model")
63
+ conf += f"; +{b['model_loc']:.0f} if the semantic pairs merge" if b.get("model_loc") else ""
64
+ conf += f"; {b['unverified_loc']:.0f} alive only by name" if b.get("unverified_loc") else ""
65
+ c = b.get("conditions", {})
66
+ stamp = ", ".join(x for x in [f"-O{c.get('opt_level')}" if c.get("opt_level") is not None else "", f"{c['linked']:.0%} linked" if c.get("linked") is not None else "", c.get("model") or ""] if x)
67
+ return {
68
+ "waste": f"{b['waste']:.1%}",
69
+ "lines": f"{b['removable_loc']:.0f} of {b['loc']} lines" + (f"; {conf}" if conf else ""),
70
+ "tangle": f"{b['tangle']:.1%}",
71
+ "reasons": ", ".join(f"{r['code']} ×{r['count']}" for r in b.get("tangle_reasons", [])[:3]),
72
+ "bloat": f"{b['score']:.1%}",
73
+ "stamp": stamp,
74
+ "tests": f"tests ({b['tests']['loc']} lines) scored apart: waste {b['tests']['waste']:.0%}" if b.get("tests", {}).get("loc") else "",
75
+ }
76
+
77
+
78
+ def liveness_parts(lv: dict | None) -> dict[str, str]:
79
+ """The live fragment of the size line, plain text: {"live": "94.1%", "defs": "448 of 476 definitions; dead: ..."}."""
80
+ from vibepiler.passes.liveness import Liveness
81
+
82
+ m = Liveness.of(lv) if lv else None
83
+ if m is None:
84
+ return {}
85
+ return {"live": f"{m.value:.1%}", "defs": str(m).split("(", 1)[1].rstrip(")")}
86
+
87
+
88
+ def summarize(program: Program) -> dict:
89
+ g = program.graph
90
+ counts = {s.label: 0 for s in SEVERITY_ORDER}
91
+ for d in program.diagnostics:
92
+ counts[d.severity.label] += 1
93
+ by_pass: dict[str, int] = defaultdict(int)
94
+ for d in program.diagnostics:
95
+ by_pass[d.pass_name] += 1
96
+ return {
97
+ "files": g.meta.get("files", 0),
98
+ "modules": len(g.nodes(NodeKind.MODULE)),
99
+ "symbols": g.meta.get("symbols", 0),
100
+ "packages": len(g.nodes(NodeKind.PACKAGE)),
101
+ "edges": len(g.edges()),
102
+ "loc": sum(m.attrs.get("loc", 0) for m in g.nodes(NodeKind.MODULE)),
103
+ "languages": g.meta.get("languages", {}),
104
+ "resolution": g.meta.get("resolution", {}),
105
+ "severity": counts,
106
+ "by_pass": dict(by_pass),
107
+ }
108
+
109
+
110
+ def project_name(program) -> str: # noqa: ANN001 - a Program
111
+ """The name a report shows: a cloned repo is named after the repo (`repo@ref`), not its cache folder
112
+ (`host__owner__repo@ref`); anything else after its folder."""
113
+ root = program.root
114
+ if root.parent.name == "repos" and "__" in root.name:
115
+ return root.name.rsplit("__", 1)[-1]
116
+ return root.name
@@ -0,0 +1,73 @@
1
+ """Graphviz DOT output."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from vibepiler.backend.common import EDGE_STYLES, KIND_COLORS, cycle_edges, diagnostics_by_node, short_label, worst_severity
6
+ from vibepiler.ir.graph import ProgramGraph
7
+ from vibepiler.ir.model import Edge, EdgeKind, Node, NodeKind
8
+ from vibepiler.ir.program import Program
9
+ from vibepiler.passes.diagnostic import Severity
10
+
11
+
12
+ def _q(s: str) -> str:
13
+ return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"'
14
+
15
+
16
+ def emit_dot(program: Program, level: str = "module", include_packages: bool = True) -> str:
17
+ g = program.graph
18
+ diags = diagnostics_by_node(program)
19
+ lines = ["digraph vibepiler {", ' rankdir=LR; node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=10]; edge [fontname="Helvetica", fontsize=8];']
20
+ if level == "module":
21
+ lines += [_node_line(n, diags) for n in g.nodes(NodeKind.MODULE)]
22
+ else:
23
+ lines += _module_clusters(g, diags)
24
+ if include_packages:
25
+ lines += [_node_line(n, diags) for n in g.nodes(NodeKind.PACKAGE)]
26
+ lines += _module_edges(program, include_packages) if level == "module" else _symbol_edges(g, include_packages)
27
+ lines.append("}")
28
+ return "\n".join(lines) + "\n"
29
+
30
+
31
+ def _node_line(n: Node, diags: dict, indent: str = " ") -> str:
32
+ """A node filled by its kind, outlined by its worst finding, dashed when nothing reaches it."""
33
+ pen = {Severity.ERROR: ', color="#C00000", penwidth=3', Severity.WARNING: ', color="#E07B00", penwidth=2'}.get(worst_severity(diags.get(n.id, [])), "")
34
+ if n.attrs.get("reachable") is False and n.kind is not NodeKind.PACKAGE:
35
+ pen += ', style="rounded,filled,dashed", fontcolor="#777777"'
36
+ return f"{indent}{_q(n.id)} [label={_q(short_label(n))}, fillcolor={_q(KIND_COLORS[n.kind] + '33')}{pen}];"
37
+
38
+
39
+ def _module_clusters(g: ProgramGraph, diags: dict) -> list[str]:
40
+ """One cluster per module holding its symbols."""
41
+ inside: dict[str | None, list[Node]] = {}
42
+ for c in g.nodes():
43
+ inside.setdefault(c.module, []).append(c)
44
+ lines = []
45
+ for i, m in enumerate(g.nodes(NodeKind.MODULE)):
46
+ lines += [f" subgraph cluster_{i} {{", f" label={_q(m.name)}; style=rounded; color=\"#BBBBBB\";", _node_line(m, diags, " ")]
47
+ lines += [_node_line(c, diags, " ") for c in inside.get(m.id, [])]
48
+ lines.append(" }")
49
+ return lines
50
+
51
+
52
+ def _shown(g: ProgramGraph, e: Edge, include_packages: bool) -> bool:
53
+ return not e.attrs.get("implicit") and (include_packages or g.node(e.dst).kind is not NodeKind.PACKAGE)
54
+
55
+
56
+ def _module_edges(program: Program, include_packages: bool) -> list[str]:
57
+ g, cyc = program.graph, cycle_edges(program)
58
+ lines = []
59
+ for e in g.edges(EdgeKind.IMPORTS):
60
+ if _shown(g, e, include_packages):
61
+ color = "red" if (e.src, e.dst) in cyc else EDGE_STYLES[EdgeKind.IMPORTS][0]
62
+ lines.append(f" {_q(e.src)} -> {_q(e.dst)} [color={_q(color)}{', penwidth=2' if color == 'red' else ''}];")
63
+ return lines
64
+
65
+
66
+ def _symbol_edges(g: ProgramGraph, include_packages: bool) -> list[str]:
67
+ lines = []
68
+ for e in g.edges((EdgeKind.CALLS, EdgeKind.REFERENCES, EdgeKind.INHERITS, EdgeKind.IMPORTS)):
69
+ if not _shown(g, e, include_packages) or (e.kind is EdgeKind.IMPORTS and g.node(e.dst).kind is not NodeKind.PACKAGE):
70
+ continue # module imports are implied by symbol edges at this level
71
+ color, style = EDGE_STYLES[e.kind]
72
+ lines.append(f" {_q(e.src)} -> {_q(e.dst)} [color={_q(color)}, style={style}];")
73
+ return lines
@@ -0,0 +1,75 @@
1
+ """Self-contained interactive HTML viewer.
2
+
3
+ The page (viewer.html next to this file) is organized around the compiler
4
+ phases: Parse -> Link -> Program graph -> Passes. The graph uses a
5
+ deterministic layered layout computed from the entry points, so toggling
6
+ filters never moves a node; cytoscape.js is loaded from cdnjs and the whole
7
+ IR is embedded as JSON.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import json
13
+ from html import escape
14
+ from importlib import resources
15
+
16
+ from vibepiler.backend.common import project_name, summarize
17
+ from vibepiler.backend.json_out import emit_json
18
+ from vibepiler.ir.program import Program
19
+ from vibepiler.passes.registry import all_passes
20
+
21
+ CYTOSCAPE = "https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.30.4/cytoscape.min.js"
22
+
23
+
24
+ MAX_SOURCE_LINES = 40 # per function on the meaning map
25
+ MAX_SOURCE_CHARS = 4_000_000 # over the whole report, so a huge repo still yields a page a browser opens
26
+
27
+
28
+ def emit_html(program: Program) -> str:
29
+ s = summarize(program)
30
+ payload = emit_json(program)
31
+ payload["sources"] = _map_sources(program)
32
+ data = json.dumps(payload, separators=(",", ":")).replace("</", "<\\/")
33
+ passes = json.dumps([{"name": p.name, "analogue": p.analogue, "description": p.description, "cost": p.cost} for p in all_passes()])
34
+ res = s["resolution"]
35
+ total = res.get("calls_total", 0)
36
+ linked = res.get("calls_resolved", 0) + res.get("calls_external", 0) + res.get("calls_builtin", 0)
37
+ pct = f"{linked / total:.0%}" if total else "n/a"
38
+ return (
39
+ resources.files("vibepiler.backend").joinpath("viewer.html").read_text(encoding="utf-8")
40
+ .replace("__CYTOSCAPE__", CYTOSCAPE)
41
+ .replace("__NAME__", escape(project_name(program)))
42
+ .replace("__FILES__", str(s["files"]))
43
+ .replace("__SYMBOLS__", str(s["symbols"]))
44
+ .replace("__LINKED__", pct)
45
+ .replace("__EDGES__", str(s["edges"]))
46
+ .replace("__FINDINGS__", str(len(program.diagnostics)))
47
+ .replace("__PASSES__", passes)
48
+ .replace("__DATA__", data)
49
+ )
50
+
51
+
52
+ def _map_sources(program: Program) -> dict[str, str]:
53
+ """The first lines of every function on the meaning map, so clicking a dot shows its code without the repo."""
54
+ points = (program.metrics.get("concepts") or {}).get("points") or []
55
+ out: dict[str, str] = {}
56
+ files: dict[str, list[str]] = {}
57
+ total = 0
58
+ for p in points:
59
+ if not program.graph.has_node(p["id"]):
60
+ continue
61
+ n = program.graph.node(p["id"])
62
+ if not n.file or not n.start_line:
63
+ continue
64
+ if n.file not in files:
65
+ try:
66
+ files[n.file] = (program.root / n.file).read_text(encoding="utf-8", errors="replace").splitlines()
67
+ except OSError:
68
+ files[n.file] = []
69
+ lines = files[n.file][n.start_line - 1 : n.start_line - 1 + min(MAX_SOURCE_LINES, max(1, n.loc))]
70
+ text = "\n".join(lines)
71
+ if total + len(text) > MAX_SOURCE_CHARS:
72
+ break
73
+ out[p["id"]] = text
74
+ total += len(text)
75
+ return out
@@ -0,0 +1,30 @@
1
+ """JSON IR: the whole graph, every diagnostic and every metric."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from vibepiler import __version__
8
+ from vibepiler.ir.program import Program
9
+
10
+
11
+ def _clean(obj: Any) -> Any:
12
+ if isinstance(obj, dict):
13
+ return {str(k): _clean(v) for k, v in obj.items() if not str(k).startswith("_")}
14
+ if isinstance(obj, (list, tuple, set, frozenset)):
15
+ return [_clean(v) for v in obj]
16
+ if isinstance(obj, (str, int, float, bool)) or obj is None:
17
+ return obj
18
+ return str(obj)
19
+
20
+
21
+ def emit_json(program: Program) -> dict[str, Any]:
22
+ data = program.graph.to_dict()
23
+ return {
24
+ "vibepiler": __version__,
25
+ "meta": _clean(data["meta"]),
26
+ "nodes": _clean(data["nodes"]),
27
+ "edges": _clean(data["edges"]),
28
+ "diagnostics": [_clean(d.to_dict()) for d in program.diagnostics],
29
+ "metrics": _clean(program.metrics),
30
+ }
@@ -0,0 +1,170 @@
1
+ """Markdown report."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections import defaultdict
6
+
7
+ from vibepiler.backend.common import liveness_parts, project_name, size_parts, summarize
8
+ from vibepiler.ir.program import Program
9
+ from vibepiler.passes.diagnostic import Diagnostic
10
+ from vibepiler.passes.measures import METRICS
11
+ from vibepiler.passes.metric import Share
12
+ from vibepiler.passes.registry import all_passes
13
+
14
+
15
+ def _table(headers: list[str], rows: list[list[str]]) -> str:
16
+ out = ["| " + " | ".join(headers) + " |", "|" + "|".join("---" for _ in headers) + "|"]
17
+ out += ["| " + " | ".join(str(c) for c in r) + " |" for r in rows]
18
+ return "\n".join(out)
19
+
20
+
21
+ def _summary(program: Program) -> list[str]:
22
+ s = summarize(program)
23
+ lines = ["## Summary", ""]
24
+ lines.append(
25
+ _table(
26
+ ["files", "modules", "symbols", "lines", "external packages", "edges", "errors", "warnings", "infos"],
27
+ [[s["files"], s["modules"], s["symbols"], s["loc"], s["packages"], s["edges"], s["severity"]["error"], s["severity"]["warning"], s["severity"]["info"]]],
28
+ )
29
+ )
30
+ res = s["resolution"]
31
+ if res:
32
+ total = res.get("calls_total", 0) or 1
33
+ resolved = res.get("calls_resolved", 0) + res.get("calls_external", 0) + res.get("calls_builtin", 0)
34
+ lines += ["", f"Call resolution: {resolved}/{total} call sites linked ({resolved / total:.0%}); {res.get('calls_unresolved', 0)} dynamic/unknown receivers."]
35
+ return lines
36
+
37
+
38
+ def _size(m: dict) -> list[str]:
39
+ """The size line and the per-folder table, like `size` on a binary."""
40
+ b = m["bloat_score"]
41
+ p, lv = size_parts(b), liveness_parts(m.get("liveness_score"))
42
+ live = f" · **live {lv['live']}** ({lv['defs']})" if lv else ""
43
+ line = f"**waste {p['waste']}** ({p['lines']}) · **tangle {p['tangle']}**" + (f" ({p['reasons']})" if p["reasons"] else "") + f" · **bloat {p['bloat']}**" + live + (f" — measured at {p['stamp']}" if p["stamp"] else "") + f". `{b['formula']}`." + (f" {p['tests'].capitalize()}." if p["tests"] else "")
44
+ live_by = {f["path"]: f for f in (m.get("liveness_score") or {}).get("folders", [])}
45
+ rows = [[f"`{f['path']}`", str(f["modules"]), str(f["loc"]), f"{f['score']:.0%}", f"{f['waste']:.0%}", f"{f['tangle']:.2f}", f"{live_by[f['path']]['value']:.1%}" if f["path"] in live_by else ""] for f in b["folders"][:15]]
46
+ return ["", line, "", _table(["folder", "modules", "lines", "bloat", "waste", "tangle", "live"], rows)]
47
+
48
+
49
+ def _what_can_go(m: dict) -> list[str]:
50
+ rows = []
51
+ if "dead_code" in m:
52
+ rows.append(["dead code", f"{m['dead_code']['symbols']} symbols, {m['dead_code']['loc']} lines", "delete"])
53
+ if "duplicates" in m:
54
+ rows.append(["duplicate functions", f"{m['duplicates']['exact_groups']} groups, {m['duplicates']['removable_loc']} removable lines; {m['duplicates']['near_pairs']} near-duplicate pairs", "merge"])
55
+ if "wrappers" in m:
56
+ rows.append(["pass-through wrappers", f"{m['wrappers']['count']} functions, {m['wrappers']['chains']} chains", "inline"])
57
+ if "abstraction" in m:
58
+ rows.append(["needless abstraction", f"{m['abstraction']['count']} findings", "flatten"])
59
+ if "bloat" in m:
60
+ b = m["bloat"]
61
+ rows.append(["dependency bloat", f"{b['unused_dependencies']} unused, {b['undeclared_dependencies']} undeclared", "prune manifest"])
62
+ rows.append(["defensive boilerplate", f"{b['swallowed_exceptions']} swallowed exceptions, {b['redundant_try']} redundant try blocks, {b['stubs']} stubs", "remove"])
63
+ if "unused_imports" in m:
64
+ rows.append(["unused imports", str(m["unused_imports"]["count"]), "remove"])
65
+ if "cycles" in m:
66
+ rows.append(["import cycles", f"{m['cycles']['count']} (largest {m['cycles']['largest']} modules)", "break"])
67
+ return ["", "### What can go", "", _table(["category", "found", "action"], rows)] if rows else ["", "### What can go", ""]
68
+
69
+
70
+ def _entry_points(ep: dict) -> list[str]:
71
+ lines = ["", "## Entry points", "", f"{ep['count']} roots; {ep['reachable_symbols']}/{ep['total_symbols']} symbols reachable from them.", ""]
72
+ lines.append(_table(["root", "kind", "location"], [[f"`{r['qualname']}`", ", ".join(r["kinds"]), f"{r['file']}:{r['line']}" if r["line"] else r["file"]] for r in ep["roots"][:60]]))
73
+ if ep["unreachable_modules"]:
74
+ lines += ["", "Modules never imported or executed: " + ", ".join(f"`{f}`" for f in ep["unreachable_modules"][:30])]
75
+ return lines
76
+
77
+
78
+ def _hotspots(hs: dict) -> list[str]:
79
+ lines = ["", "## Hotspots", "", "Modules by fan-in + fan-out:", ""]
80
+ lines.append(_table(["module", "fan-in", "fan-out", "external deps", "lines"], [[f"`{r['name']}`", r["fan_in"], r["fan_out"], r["external_deps"], r["loc"]] for r in hs["modules"]]))
81
+ lines += ["", "Most central functions (PageRank over the call graph):", ""]
82
+ lines.append(_table(["function", "callers", "callees", "pagerank"], [[f"`{r['qualname']}`", r["callers"], r["callees"], r["pagerank"]] for r in hs["functions"]]))
83
+ return lines
84
+
85
+
86
+ def _complexity(c: dict) -> list[str]:
87
+ lines = ["", "## Complexity", "", f"{c['functions']} functions, the hardest to follow first; average cyclomatic complexity {c['avg']}, max {c['max']}.", ""]
88
+ lines.append(_table(["function", "cognitive", "cyclomatic", "lines", "nesting"], [[f"`{r['qualname']}`", r["cognitive"], r["complexity"], r["loc"], r["nesting"]] for r in c["top"]]))
89
+ return lines
90
+
91
+
92
+ READING = (
93
+ "Each is 0–1, read one of two ways. A **share** (typed, documented) is a plain percentage: how much of the code has it. "
94
+ "An **excess** score (cognitive, cyclomatic, mi) is the share of complexity past the limit, weighted by lines: a function at "
95
+ "twice the limit scores 0.5, one within it 0, so 0.4 is not \"40% of functions\". How widespread it is reads beside it, as the "
96
+ "functions and the share of lines over the limit; how bad, as the worst raw number."
97
+ )
98
+
99
+
100
+ def _fmt(cls: type, v: float) -> str:
101
+ """A share as a percent; an excess score as a decimal, so it is not read as a share of functions."""
102
+ return f"{v:.1%}" if issubclass(cls, Share) else f"{v:.2f}"
103
+
104
+
105
+ def _metrics(m: dict) -> list[str]:
106
+ """Every measure with its raw numbers, then each one per folder (the same folders as the size table)."""
107
+ have = [(cls, cls.of(m[f"{cls.key}_score"])) for cls in METRICS if m.get(f"{cls.key}_score")]
108
+ if not have:
109
+ return []
110
+ rows = [[f"**{cls.label}**", _fmt(cls, x.value), str(x).split(" (", 1)[1].rstrip(")"), "lower" if cls.better == "low" else "higher", f"`{cls.formula}`"] for cls, x in have]
111
+ lines = ["", "### Metrics", "", READING, "", _table(["metric", "value", "raw", "better", "formula"], rows)]
112
+ by = {cls.key: {f["path"]: f["value"] for f in m[f"{cls.key}_score"]["folders"]} for cls, _ in have}
113
+ folders = [f["path"] for f in (m.get("bloat_score") or {}).get("folders", [])][:15] or list(next(iter(by.values())))[:15]
114
+ lines += ["", _table(["folder", *(cls.label for cls, _ in have)], [[f"`{p}`", *(_fmt(cls, by[cls.key][p]) if p in by[cls.key] else "" for cls, _ in have)] for p in folders])]
115
+ return lines
116
+
117
+
118
+ def _concepts(program: Program, c: dict) -> list[str]:
119
+ lines = ["", "## Concepts (-O3)", "", f"{len(c['concepts'])} concepts cover {c['clustered']} of {c['symbols']} functions, grouped by meaning with `{c['model']}`, regardless of where they live. A concept spread over several modules with no clear home is a scattered concern.", ""]
120
+ rows = [[f"`{x['label']}`", str(x["size"]), str(len(x["modules"])), f"`{program.graph.node(x['exemplar']).qualname}`", "scattered" if x["scattered"] else ""] for x in c["concepts"][:30]]
121
+ return lines + [_table(["concept", "functions", "modules", "exemplar", ""], rows)]
122
+
123
+
124
+ def _plan(plan: list[dict]) -> list[str]:
125
+ rows = [[f"{p['lines']:.0f}", p["action"], p["confidence"], p["code"], f"`{p['qualname']}`" if p["qualname"] else "", f"{p['file']}:{p['line']}" if p["line"] else (p["file"] or "")] for p in plan[:40]]
126
+ return ["", "## Elimination plan", "", "Findings ordered by lines freed. Apply the top one, re-run, repeat: the score is a fixpoint iteration.", "", _table(["lines", "action", "confidence", "finding", "symbol", "where"], rows)]
127
+
128
+
129
+ def _findings(program: Program, max_per_pass: int) -> list[str]:
130
+ by_pass: dict[str, list[Diagnostic]] = defaultdict(list)
131
+ for d in program.diagnostics:
132
+ by_pass[d.pass_name].append(d)
133
+ lines = ["", "## Findings by pass", ""]
134
+ for p in all_passes():
135
+ diags = by_pass.get(p.name)
136
+ if not diags:
137
+ continue
138
+ lines += [f"### {p.name} ({len(diags)}) — {p.analogue}", "", f"_{p.description}_", ""]
139
+ diags = sorted(diags, key=lambda d: (-int(d.severity), d.file or "", d.line or 0))
140
+ for d in diags[:max_per_pass]:
141
+ loc = f"`{d.location}`" if d.file else ""
142
+ lines.append(f"- **{d.severity.label}** `{d.code}` {loc}: {d.message}" + (f" \n _{d.suggestion}_" if d.suggestion else ""))
143
+ if len(diags) > max_per_pass:
144
+ lines.append(f"- … {len(diags) - max_per_pass} more (see ir.json)")
145
+ lines.append("")
146
+ return lines
147
+
148
+
149
+ def emit_markdown(program: Program, max_per_pass: int = 40) -> str:
150
+ m = program.metrics
151
+ b = m.get("bloat_score")
152
+ lines = [f"# Vibepiler report for `{project_name(program)}`", ""]
153
+ lines += _summary(program)
154
+ if b:
155
+ lines += _size(m)
156
+ lines += _metrics(m)
157
+ lines += _what_can_go(m)
158
+ if "entry_points" in m:
159
+ lines += _entry_points(m["entry_points"])
160
+ if "hotspots" in m:
161
+ lines += _hotspots(m["hotspots"])
162
+ if "complexity" in m and m["complexity"]["top"]:
163
+ lines += _complexity(m["complexity"])
164
+ c = m.get("concepts")
165
+ if c and c.get("concepts"):
166
+ lines += _concepts(program, c)
167
+ if b and b.get("plan"):
168
+ lines += _plan(b["plan"])
169
+ lines += _findings(program, max_per_pass)
170
+ return "\n".join(lines).rstrip() + "\n"
@@ -0,0 +1,41 @@
1
+ """Mermaid flowchart of the module graph (pasteable into a README or GitHub issue)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+
7
+ from vibepiler.backend.common import cycle_edges
8
+ from vibepiler.ir.model import EdgeKind, NodeKind
9
+ from vibepiler.ir.program import Program
10
+
11
+
12
+ def _mid(s: str) -> str:
13
+ return "n_" + re.sub(r"[^A-Za-z0-9_]", "_", s)
14
+
15
+
16
+ def emit_mermaid(program: Program, include_packages: bool = False, max_nodes: int = 150) -> str:
17
+ g = program.graph
18
+ cyc = cycle_edges(program)
19
+ lines = ["flowchart LR"]
20
+ modules = g.nodes(NodeKind.MODULE)[:max_nodes]
21
+ ids = {m.id for m in modules}
22
+ for m in modules:
23
+ dead = m.attrs.get("reachable") is False
24
+ lines.append(f' {_mid(m.id)}["{m.name}"]' + (":::dead" if dead else ""))
25
+ if include_packages:
26
+ for p in g.nodes(NodeKind.PACKAGE):
27
+ ids.add(p.id)
28
+ lines.append(f' {_mid(p.id)}(["{p.name}"]):::pkg')
29
+ link_styles = []
30
+ k = 0
31
+ for e in g.edges(EdgeKind.IMPORTS):
32
+ if e.attrs.get("implicit") or e.src not in ids or e.dst not in ids:
33
+ continue
34
+ lines.append(f" {_mid(e.src)} --> {_mid(e.dst)}")
35
+ if (e.src, e.dst) in cyc:
36
+ link_styles.append(f" linkStyle {k} stroke:#d00,stroke-width:2px")
37
+ k += 1
38
+ lines += link_styles
39
+ lines.append(" classDef dead fill:#eee,stroke:#999,color:#777,stroke-dasharray: 4 2")
40
+ lines.append(" classDef pkg fill:#f4f4f4,stroke:#bbb")
41
+ return "\n".join(lines) + "\n"