dev-guru 0.1.0__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.
- dev_guru/__init__.py +21 -0
- dev_guru/__main__.py +3 -0
- dev_guru/cli.py +149 -0
- dev_guru/client/__init__.py +22 -0
- dev_guru/client/inprocess.py +122 -0
- dev_guru/client/negotiation.py +69 -0
- dev_guru/client/port.py +87 -0
- dev_guru/errors.py +44 -0
- dev_guru/reports/__init__.py +1 -0
- dev_guru/reports/assets/explorer.css +218 -0
- dev_guru/reports/assets/explorer.html +75 -0
- dev_guru/reports/assets/explorer.js +822 -0
- dev_guru/reports/model.py +264 -0
- dev_guru/reports/render.py +137 -0
- dev_guru/sdk.py +56 -0
- dev_guru/service.py +53 -0
- dev_guru/version.py +3 -0
- dev_guru-0.1.0.dist-info/METADATA +113 -0
- dev_guru-0.1.0.dist-info/RECORD +22 -0
- dev_guru-0.1.0.dist-info/WHEEL +4 -0
- dev_guru-0.1.0.dist-info/entry_points.txt +2 -0
- dev_guru-0.1.0.dist-info/licenses/LICENSE +201 -0
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
"""The explorer view model (``dev-guru/explorer@1``): a bounded projection of an Ananke graph for presentation.
|
|
2
|
+
|
|
3
|
+
Everything structural comes from Ananke: files, symbols, imports, calls, bases and their metadata. Dev Guru only
|
|
4
|
+
regroups and counts what Ananke found (packages, fan-in, the most-depended-on files, import cycles over the given
|
|
5
|
+
edges), adds source snippets for display, and states what the report doesn't cover. Output is sorted and
|
|
6
|
+
deterministic, so the same graph always gives the same model.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from collections import defaultdict
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from typing import Any
|
|
14
|
+
|
|
15
|
+
from dev_guru.client.port import GraphData
|
|
16
|
+
|
|
17
|
+
SCHEMA = "dev-guru/explorer@1"
|
|
18
|
+
MAX_SNIPPET_LINES = 60
|
|
19
|
+
MAX_SYMBOLS = 6000
|
|
20
|
+
ENTRY_NAMES = {"__main__.py", "main.py", "cli.py", "app.py", "manage.py", "wsgi.py", "asgi.py"}
|
|
21
|
+
SYMBOL_KINDS = ("class", "function", "method")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _module_name(path: str) -> str:
|
|
25
|
+
parts = path.removesuffix(".py").split("/")
|
|
26
|
+
if parts[-1] == "__init__":
|
|
27
|
+
parts = parts[:-1]
|
|
28
|
+
return ".".join(parts)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _package(path: str) -> str:
|
|
32
|
+
parent = path.rsplit("/", 1)[0] if "/" in path else "."
|
|
33
|
+
return parent
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _snippet(root: Path, path: str, line: int, end_line: int) -> str:
|
|
37
|
+
if not line:
|
|
38
|
+
return ""
|
|
39
|
+
try:
|
|
40
|
+
lines = (root / path).read_text(encoding="utf-8").splitlines()
|
|
41
|
+
except (OSError, UnicodeDecodeError):
|
|
42
|
+
return ""
|
|
43
|
+
end = min(max(end_line, line), line + MAX_SNIPPET_LINES - 1, len(lines))
|
|
44
|
+
return "\n".join(lines[line - 1 : end])
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _cycles(adjacency: dict[str, set[str]]) -> list[list[str]]:
|
|
48
|
+
"""Strongly connected components with more than one file (Tarjan, iterative, deterministic)."""
|
|
49
|
+
index: dict[str, int] = {}
|
|
50
|
+
low: dict[str, int] = {}
|
|
51
|
+
on_stack: set[str] = set()
|
|
52
|
+
stack: list[str] = []
|
|
53
|
+
out: list[list[str]] = []
|
|
54
|
+
counter = 0
|
|
55
|
+
for start in sorted(adjacency):
|
|
56
|
+
if start in index:
|
|
57
|
+
continue
|
|
58
|
+
work: list[tuple[str, list[str]]] = [(start, sorted(adjacency.get(start, ())))]
|
|
59
|
+
index[start] = low[start] = counter
|
|
60
|
+
counter += 1
|
|
61
|
+
stack.append(start)
|
|
62
|
+
on_stack.add(start)
|
|
63
|
+
while work:
|
|
64
|
+
node, children = work[-1]
|
|
65
|
+
if children:
|
|
66
|
+
child = children.pop(0)
|
|
67
|
+
if child not in index:
|
|
68
|
+
index[child] = low[child] = counter
|
|
69
|
+
counter += 1
|
|
70
|
+
stack.append(child)
|
|
71
|
+
on_stack.add(child)
|
|
72
|
+
work.append((child, sorted(adjacency.get(child, ()))))
|
|
73
|
+
elif child in on_stack:
|
|
74
|
+
low[node] = min(low[node], index[child])
|
|
75
|
+
else:
|
|
76
|
+
work.pop()
|
|
77
|
+
if work:
|
|
78
|
+
low[work[-1][0]] = min(low[work[-1][0]], low[node])
|
|
79
|
+
if low[node] == index[node]:
|
|
80
|
+
comp = []
|
|
81
|
+
while True:
|
|
82
|
+
member = stack.pop()
|
|
83
|
+
on_stack.discard(member)
|
|
84
|
+
comp.append(member)
|
|
85
|
+
if member == node:
|
|
86
|
+
break
|
|
87
|
+
if len(comp) > 1:
|
|
88
|
+
out.append(sorted(comp))
|
|
89
|
+
return sorted(out)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def build(graph: GraphData, workspace: Path, *, project_name: str | None = None) -> dict[str, Any]:
|
|
93
|
+
root = workspace.expanduser().resolve()
|
|
94
|
+
files_raw = sorted((n for n in graph.nodes if n.kind == "file"), key=lambda n: n.path)
|
|
95
|
+
symbols_raw = sorted((n for n in graph.nodes if n.kind in SYMBOL_KINDS), key=lambda n: n.id)
|
|
96
|
+
omitted_symbols = max(0, len(symbols_raw) - MAX_SYMBOLS)
|
|
97
|
+
symbols_raw = symbols_raw[:MAX_SYMBOLS]
|
|
98
|
+
known_symbols = {s.id for s in symbols_raw}
|
|
99
|
+
|
|
100
|
+
module_to_file: dict[str, str] = {}
|
|
101
|
+
for f in files_raw:
|
|
102
|
+
module = str(
|
|
103
|
+
f.metadata.get("module") or _module_name(f.path)
|
|
104
|
+
) # older Ananke has no "module"
|
|
105
|
+
if module:
|
|
106
|
+
module_to_file[module] = f.id
|
|
107
|
+
if module.startswith("src."):
|
|
108
|
+
module_to_file.setdefault(module.removeprefix("src."), f.id)
|
|
109
|
+
|
|
110
|
+
imports: set[tuple[str, str]] = set()
|
|
111
|
+
external: dict[str, set[str]] = defaultdict(set)
|
|
112
|
+
sym_edges: list[dict[str, Any]] = []
|
|
113
|
+
owner: dict[str, str] = {}
|
|
114
|
+
for e in graph.edges:
|
|
115
|
+
if e.kind == "owns":
|
|
116
|
+
owner[e.target] = e.source
|
|
117
|
+
elif e.kind == "imports" and e.source.startswith("file:"):
|
|
118
|
+
module = e.target.removeprefix("module:")
|
|
119
|
+
target = module_to_file.get(module)
|
|
120
|
+
if target is None: # `from pkg import mod` resolves to pkg.mod when that file exists
|
|
121
|
+
parts = module.split(".")
|
|
122
|
+
for cut in range(len(parts), 0, -1):
|
|
123
|
+
candidate = module_to_file.get(".".join(parts[:cut]))
|
|
124
|
+
if candidate:
|
|
125
|
+
target = candidate
|
|
126
|
+
break
|
|
127
|
+
if target and target != e.source:
|
|
128
|
+
imports.add((e.source, target))
|
|
129
|
+
elif target is None:
|
|
130
|
+
external[module.split(".")[0]].add(e.source)
|
|
131
|
+
elif (
|
|
132
|
+
e.kind in ("calls", "inherits")
|
|
133
|
+
and e.source in known_symbols
|
|
134
|
+
and e.target in known_symbols
|
|
135
|
+
):
|
|
136
|
+
at = e.location.rsplit(":", 1)[-1] if e.location else ""
|
|
137
|
+
sym_edges.append(
|
|
138
|
+
{
|
|
139
|
+
"s": e.source,
|
|
140
|
+
"t": e.target,
|
|
141
|
+
"k": e.kind,
|
|
142
|
+
"o": e.origin,
|
|
143
|
+
"line": int(at) if at.isdigit() else 0,
|
|
144
|
+
}
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
def file_of(symbol_id: str) -> str:
|
|
148
|
+
cur = symbol_id
|
|
149
|
+
while cur in owner and not cur.startswith("file:"):
|
|
150
|
+
cur = owner[cur]
|
|
151
|
+
return cur if cur.startswith("file:") else ""
|
|
152
|
+
|
|
153
|
+
fan_in: dict[str, int] = defaultdict(int)
|
|
154
|
+
fan_out: dict[str, int] = defaultdict(int)
|
|
155
|
+
adjacency: dict[str, set[str]] = defaultdict(set)
|
|
156
|
+
for importer, imported in imports:
|
|
157
|
+
fan_out[importer] += 1
|
|
158
|
+
fan_in[imported] += 1
|
|
159
|
+
adjacency[importer].add(imported)
|
|
160
|
+
calls_in: dict[str, int] = defaultdict(int)
|
|
161
|
+
calls_out: dict[str, int] = defaultdict(int)
|
|
162
|
+
for sym_edge in sym_edges:
|
|
163
|
+
if sym_edge["k"] == "calls":
|
|
164
|
+
calls_out[sym_edge["s"]] += 1
|
|
165
|
+
calls_in[sym_edge["t"]] += 1
|
|
166
|
+
|
|
167
|
+
by_file: dict[str, list[str]] = defaultdict(list)
|
|
168
|
+
symbols: list[dict[str, Any]] = []
|
|
169
|
+
for sym in symbols_raw:
|
|
170
|
+
meta = sym.metadata
|
|
171
|
+
line, end = int(str(meta.get("line") or 0)), int(str(meta.get("end_line") or 0))
|
|
172
|
+
fid = file_of(sym.id)
|
|
173
|
+
by_file[fid].append(sym.id)
|
|
174
|
+
symbols.append(
|
|
175
|
+
{
|
|
176
|
+
"id": sym.id,
|
|
177
|
+
"kind": sym.kind,
|
|
178
|
+
"name": sym.name,
|
|
179
|
+
"file": fid,
|
|
180
|
+
"line": line,
|
|
181
|
+
"end_line": end,
|
|
182
|
+
"signature": str(meta.get("signature") or ""),
|
|
183
|
+
"doc": str(meta.get("doc") or ""),
|
|
184
|
+
"source": _snippet(root, sym.path, line, end),
|
|
185
|
+
"calls_in": calls_in.get(sym.id, 0),
|
|
186
|
+
"calls_out": calls_out.get(sym.id, 0),
|
|
187
|
+
}
|
|
188
|
+
)
|
|
189
|
+
|
|
190
|
+
files: list[dict[str, Any]] = []
|
|
191
|
+
packages: dict[str, list[str]] = defaultdict(list)
|
|
192
|
+
for node in files_raw:
|
|
193
|
+
pkg = _package(node.path)
|
|
194
|
+
packages[pkg].append(node.id)
|
|
195
|
+
files.append(
|
|
196
|
+
{
|
|
197
|
+
"id": node.id,
|
|
198
|
+
"path": node.path,
|
|
199
|
+
"name": node.name,
|
|
200
|
+
"package": pkg,
|
|
201
|
+
"module": str(node.metadata.get("module") or _module_name(node.path)),
|
|
202
|
+
"loc": int(str(node.metadata.get("loc") or 0)),
|
|
203
|
+
"doc": str(node.metadata.get("doc") or ""),
|
|
204
|
+
"parse_error": bool(node.metadata.get("parse_error", False)),
|
|
205
|
+
"symbols": sorted(by_file.get(node.id, [])),
|
|
206
|
+
"fan_in": fan_in.get(node.id, 0),
|
|
207
|
+
"fan_out": fan_out.get(node.id, 0),
|
|
208
|
+
"external": sorted(m for m, users in external.items() if node.id in users),
|
|
209
|
+
"entry": node.name in ENTRY_NAMES,
|
|
210
|
+
}
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
ranked_in = sorted(files, key=lambda f: (-f["fan_in"], f["path"]))
|
|
214
|
+
ranked_loc = sorted(files, key=lambda f: (-f["loc"], f["path"]))
|
|
215
|
+
connected = {s for s, _ in imports} | {t for _, t in imports}
|
|
216
|
+
limitations = [
|
|
217
|
+
"Static analysis of Python source by Ananke's native graph provider; nothing was executed.",
|
|
218
|
+
"Calls and base classes are inferred through each file's imports: dynamic dispatch, getattr and "
|
|
219
|
+
"re-exports beyond one level are not followed.",
|
|
220
|
+
"Imports of modules outside the workspace are listed as external dependencies, not analysed.",
|
|
221
|
+
]
|
|
222
|
+
if omitted_symbols:
|
|
223
|
+
limitations.append(f"{omitted_symbols} symbols were omitted to keep the report bounded.")
|
|
224
|
+
parse_errors = [f["path"] for f in files if f["parse_error"]]
|
|
225
|
+
if parse_errors:
|
|
226
|
+
limitations.append(f"{len(parse_errors)} file(s) could not be parsed and show no symbols.")
|
|
227
|
+
return {
|
|
228
|
+
"schema": SCHEMA,
|
|
229
|
+
"project": {
|
|
230
|
+
"name": project_name or root.name,
|
|
231
|
+
"files": len(files),
|
|
232
|
+
"packages": len(packages),
|
|
233
|
+
"symbols": len(symbols),
|
|
234
|
+
"loc": sum(f["loc"] for f in files),
|
|
235
|
+
"imports": len(imports),
|
|
236
|
+
"calls": sum(1 for e in sym_edges if e["k"] == "calls"),
|
|
237
|
+
"external": len(external),
|
|
238
|
+
},
|
|
239
|
+
"packages": [
|
|
240
|
+
{"id": p, "name": p, "files": sorted(ids)} for p, ids in sorted(packages.items())
|
|
241
|
+
],
|
|
242
|
+
"files": files,
|
|
243
|
+
"symbols": symbols,
|
|
244
|
+
"edges": [
|
|
245
|
+
{"s": s, "t": t, "k": "imports", "o": "extracted", "line": 0}
|
|
246
|
+
for s, t in sorted(imports)
|
|
247
|
+
]
|
|
248
|
+
+ sorted(sym_edges, key=lambda e: (e["s"], e["t"], e["k"])),
|
|
249
|
+
"external": [
|
|
250
|
+
{"name": m, "importers": sorted(users)} for m, users in sorted(external.items())
|
|
251
|
+
],
|
|
252
|
+
"insights": {
|
|
253
|
+
"most_depended": [f["id"] for f in ranked_in if f["fan_in"]][:8],
|
|
254
|
+
"largest": [f["id"] for f in ranked_loc if f["loc"]][:8],
|
|
255
|
+
"entry_points": [f["id"] for f in files if f["entry"]],
|
|
256
|
+
"cycles": _cycles(adjacency),
|
|
257
|
+
"isolated": [f["id"] for f in files if f["id"] not in connected],
|
|
258
|
+
},
|
|
259
|
+
"limitations": limitations,
|
|
260
|
+
"omitted": {"symbols": omitted_symbols},
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
__all__ = ["SCHEMA", "build"]
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
"""Render an explorer view model into one self-contained, offline HTML file.
|
|
2
|
+
|
|
3
|
+
Guarantees (tests/test_reports.py):
|
|
4
|
+
|
|
5
|
+
- **Offline.** CSS and JavaScript are inlined; no CDN, font, telemetry or network URL is referenced.
|
|
6
|
+
- **Safe.** The data is embedded as JSON in a ``<script type="application/json">`` block with ``<``, ``>``, ``&``
|
|
7
|
+
and the U+2028/U+2029 separators escaped, so source text can never close the script or run as HTML. The page
|
|
8
|
+
shows all untrusted text through ``textContent``.
|
|
9
|
+
- **View-only.** Opening the file runs no command and contacts no server. Requests for deeper analysis download a
|
|
10
|
+
request file for Dev Guru or Ananke to run explicitly.
|
|
11
|
+
- **Traceable.** A manifest records the renderer version, the harness version, the input digest and the workspace
|
|
12
|
+
revision. It is embedded in the page and written next to it as ``<name>.manifest.json``.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import hashlib
|
|
18
|
+
import html
|
|
19
|
+
import json
|
|
20
|
+
import os
|
|
21
|
+
import re
|
|
22
|
+
import subprocess
|
|
23
|
+
from datetime import UTC, datetime
|
|
24
|
+
from importlib import resources
|
|
25
|
+
from pathlib import Path
|
|
26
|
+
from typing import Any
|
|
27
|
+
|
|
28
|
+
from dev_guru.version import __version__
|
|
29
|
+
|
|
30
|
+
RENDERER = "dev-guru/explorer-html@1"
|
|
31
|
+
PLACEHOLDER = re.compile(r"\{\{(TITLE|CSS|JS|DATA|MANIFEST)\}\}")
|
|
32
|
+
LS, PS = (
|
|
33
|
+
chr(0x2028),
|
|
34
|
+
chr(0x2029),
|
|
35
|
+
) # line/paragraph separators: legal in JSON, not in older JS string literals
|
|
36
|
+
MANIFEST_SCHEMA = "dev-guru/report-manifest@1"
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def safe_json(data: Any) -> str:
|
|
40
|
+
"""JSON that is safe inside an HTML ``<script>`` element."""
|
|
41
|
+
text = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
|
|
42
|
+
return (
|
|
43
|
+
text.replace("&", "\\u0026")
|
|
44
|
+
.replace("<", "\\u003c")
|
|
45
|
+
.replace(">", "\\u003e")
|
|
46
|
+
.replace(LS, "\\u2028")
|
|
47
|
+
.replace(PS, "\\u2029")
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def digest(data: Any) -> str:
|
|
52
|
+
canonical = json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
|
|
53
|
+
return "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _git(root: Path, *args: str, timeout: int = 5) -> subprocess.CompletedProcess[str]:
|
|
57
|
+
"""A fixed git argv (no shell); git comes from PATH like any developer tool."""
|
|
58
|
+
argv = ["git", "-C", str(root), *args]
|
|
59
|
+
return subprocess.run(argv, capture_output=True, text=True, timeout=timeout, check=False) # noqa: S603
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _revision(root: Path) -> dict[str, Any]:
|
|
63
|
+
try:
|
|
64
|
+
head = _git(root, "rev-parse", "HEAD")
|
|
65
|
+
if head.returncode != 0:
|
|
66
|
+
return {"vcs": None}
|
|
67
|
+
dirty = _git(root, "status", "--porcelain", "--untracked-files=no", timeout=10)
|
|
68
|
+
return {"vcs": "git", "commit": head.stdout.strip(), "dirty": bool(dirty.stdout.strip())}
|
|
69
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
70
|
+
return {"vcs": None}
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def _generated_at() -> str:
|
|
74
|
+
epoch = os.environ.get("SOURCE_DATE_EPOCH") # reproducible builds
|
|
75
|
+
moment = (
|
|
76
|
+
datetime.fromtimestamp(int(epoch), UTC) if epoch and epoch.isdigit() else datetime.now(UTC)
|
|
77
|
+
)
|
|
78
|
+
return moment.replace(microsecond=0).isoformat()
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def manifest(
|
|
82
|
+
model: dict[str, Any], *, workspace: Path, ananke_version: str | None, snapshot_id: str
|
|
83
|
+
) -> dict[str, Any]:
|
|
84
|
+
return {
|
|
85
|
+
"schema": MANIFEST_SCHEMA,
|
|
86
|
+
"renderer": RENDERER,
|
|
87
|
+
"dev_guru": __version__,
|
|
88
|
+
"ananke": ananke_version,
|
|
89
|
+
"view_model": model["schema"],
|
|
90
|
+
"snapshot_id": snapshot_id,
|
|
91
|
+
"input_digest": digest(model),
|
|
92
|
+
"workspace": {"name": model["project"]["name"], **_revision(workspace)},
|
|
93
|
+
"publication": "offline-single-file",
|
|
94
|
+
"generated_at": _generated_at(),
|
|
95
|
+
"limitations": model["limitations"],
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _asset(name: str) -> str:
|
|
100
|
+
return resources.files("dev_guru.reports").joinpath("assets", name).read_text(encoding="utf-8")
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def render(
|
|
104
|
+
model: dict[str, Any], report_manifest: dict[str, Any], *, title: str | None = None
|
|
105
|
+
) -> str:
|
|
106
|
+
page = _asset("explorer.html")
|
|
107
|
+
name = title or f"{model['project']['name']} · Dev Guru explorer"
|
|
108
|
+
values = {
|
|
109
|
+
"TITLE": html.escape(name),
|
|
110
|
+
"CSS": _asset("explorer.css"),
|
|
111
|
+
"JS": _asset("explorer.js"),
|
|
112
|
+
"DATA": safe_json(model),
|
|
113
|
+
"MANIFEST": safe_json(report_manifest),
|
|
114
|
+
}
|
|
115
|
+
# One pass over the template only: inserted content (source code may itself contain "{{MANIFEST}}")
|
|
116
|
+
# is never scanned again.
|
|
117
|
+
return PLACEHOLDER.sub(lambda m: values[m.group(1)], page)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def write(
|
|
121
|
+
model: dict[str, Any],
|
|
122
|
+
report_manifest: dict[str, Any],
|
|
123
|
+
output: Path,
|
|
124
|
+
*,
|
|
125
|
+
title: str | None = None,
|
|
126
|
+
) -> tuple[Path, Path]:
|
|
127
|
+
output = output.expanduser()
|
|
128
|
+
output.parent.mkdir(parents=True, exist_ok=True)
|
|
129
|
+
output.write_text(render(model, report_manifest, title=title), encoding="utf-8")
|
|
130
|
+
sidecar = output.with_name(output.name + ".manifest.json")
|
|
131
|
+
sidecar.write_text(
|
|
132
|
+
json.dumps(report_manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8"
|
|
133
|
+
)
|
|
134
|
+
return output, sidecar
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
__all__ = ["MANIFEST_SCHEMA", "RENDERER", "digest", "manifest", "render", "safe_json", "write"]
|
dev_guru/sdk.py
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""The Dev Guru Python SDK.
|
|
2
|
+
|
|
3
|
+
from dev_guru import GuruClient
|
|
4
|
+
|
|
5
|
+
with GuruClient(workspace="./my-project") as guru:
|
|
6
|
+
result = guru.explore()
|
|
7
|
+
guru.export(result, output="reports/explorer.html")
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
from types import TracebackType
|
|
14
|
+
|
|
15
|
+
from dev_guru import service
|
|
16
|
+
from dev_guru.client import AnankeClient, HarnessInfo, connect
|
|
17
|
+
from dev_guru.service import ExploreResult
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class GuruClient:
|
|
21
|
+
def __init__(self, workspace: str | Path = ".", *, transport: str = "in-process") -> None:
|
|
22
|
+
self.workspace = Path(workspace)
|
|
23
|
+
self.client: AnankeClient = connect(transport)
|
|
24
|
+
|
|
25
|
+
def __enter__(self) -> GuruClient:
|
|
26
|
+
return self
|
|
27
|
+
|
|
28
|
+
def __exit__(
|
|
29
|
+
self,
|
|
30
|
+
exc_type: type[BaseException] | None,
|
|
31
|
+
exc: BaseException | None,
|
|
32
|
+
tb: TracebackType | None,
|
|
33
|
+
) -> None:
|
|
34
|
+
return None
|
|
35
|
+
|
|
36
|
+
def doctor(self) -> HarnessInfo:
|
|
37
|
+
return self.client.info()
|
|
38
|
+
|
|
39
|
+
def explore(self, *, name: str | None = None) -> ExploreResult:
|
|
40
|
+
return service.explore(self.workspace, client=self.client, name=name)
|
|
41
|
+
|
|
42
|
+
def export(
|
|
43
|
+
self,
|
|
44
|
+
result: ExploreResult,
|
|
45
|
+
*,
|
|
46
|
+
output: str | Path,
|
|
47
|
+
format: str = "html",
|
|
48
|
+
title: str | None = None,
|
|
49
|
+
) -> Path:
|
|
50
|
+
if format != "html":
|
|
51
|
+
raise ValueError(f"unsupported export format {format!r}; supported: html")
|
|
52
|
+
page, _ = service.export_html(result, Path(output), title=title)
|
|
53
|
+
return page
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
__all__ = ["GuruClient"]
|
dev_guru/service.py
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
"""The service layer shared by the ``dev`` CLI and the Python SDK (neither parses the other's output)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from dev_guru import errors
|
|
10
|
+
from dev_guru.client import AnankeClient, connect
|
|
11
|
+
from dev_guru.reports import model as explorer_model
|
|
12
|
+
from dev_guru.reports import render
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class ExploreResult:
|
|
17
|
+
"""What ``explore`` produced: the view model and its manifest, before or after export."""
|
|
18
|
+
|
|
19
|
+
workspace: Path
|
|
20
|
+
model: dict[str, Any]
|
|
21
|
+
manifest: dict[str, Any]
|
|
22
|
+
transport: str
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def explore(
|
|
26
|
+
workspace: Path, *, client: AnankeClient | None = None, name: str | None = None
|
|
27
|
+
) -> ExploreResult:
|
|
28
|
+
client = client or connect()
|
|
29
|
+
root = workspace.expanduser().resolve()
|
|
30
|
+
graph = client.graph_data(root)
|
|
31
|
+
model = explorer_model.build(graph, root, project_name=name)
|
|
32
|
+
if not model["files"]:
|
|
33
|
+
raise errors.GuruError(
|
|
34
|
+
errors.WORKSPACE_INVALID,
|
|
35
|
+
f"Ananke found no Python files in {root}",
|
|
36
|
+
hint="point dev explore at a project directory that contains .py files",
|
|
37
|
+
)
|
|
38
|
+
report_manifest = render.manifest(
|
|
39
|
+
model, workspace=root, ananke_version=graph.ananke_version, snapshot_id=graph.snapshot_id
|
|
40
|
+
)
|
|
41
|
+
report_manifest["transport"] = client.transport
|
|
42
|
+
return ExploreResult(
|
|
43
|
+
workspace=root, model=model, manifest=report_manifest, transport=client.transport
|
|
44
|
+
)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def export_html(
|
|
48
|
+
result: ExploreResult, output: Path, *, title: str | None = None
|
|
49
|
+
) -> tuple[Path, Path]:
|
|
50
|
+
return render.write(result.model, result.manifest, output, title=title)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
__all__ = ["ExploreResult", "explore", "export_html"]
|
dev_guru/version.py
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: dev-guru
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Dev Guru: understand, improve, verify and learn from your software. A local-first developer product on the Ananke Plexus harness: Python SDK and CLI first, offline HTML reports, later a local web UI.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Neo-Pragnya/Dev-Guru
|
|
6
|
+
Project-URL: Repository, https://github.com/Neo-Pragnya/Dev-Guru
|
|
7
|
+
Project-URL: Issues, https://github.com/Neo-Pragnya/Dev-Guru/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/Neo-Pragnya/Dev-Guru/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Neo Pragnya
|
|
10
|
+
License-Expression: Apache-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,ananke,code-understanding,developer-tools,reports
|
|
13
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.11
|
|
25
|
+
Requires-Dist: ananke-plexus<0.4,>=0.3.12
|
|
26
|
+
Requires-Dist: pydantic<3,>=2.11
|
|
27
|
+
Requires-Dist: rich>=13
|
|
28
|
+
Requires-Dist: typer<1,>=0.16
|
|
29
|
+
Provides-Extra: dev
|
|
30
|
+
Requires-Dist: hatchling>=1.26; extra == 'dev'
|
|
31
|
+
Requires-Dist: mypy>=1.15; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest-bdd>=8; extra == 'dev'
|
|
33
|
+
Requires-Dist: pytest-cov>=6; extra == 'dev'
|
|
34
|
+
Requires-Dist: pytest-xdist>=3; extra == 'dev'
|
|
35
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
36
|
+
Requires-Dist: pyyaml>=6; extra == 'dev'
|
|
37
|
+
Requires-Dist: ruff>=0.12; extra == 'dev'
|
|
38
|
+
Requires-Dist: types-pyyaml>=6; extra == 'dev'
|
|
39
|
+
Provides-Extra: dex
|
|
40
|
+
Requires-Dist: dex-trove>=0.1.6; extra == 'dex'
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# Dev Guru
|
|
44
|
+
|
|
45
|
+
**See your code. Understand it. Change it with confidence.**
|
|
46
|
+
|
|
47
|
+
Point Dev Guru at a Python project and get **one offline HTML explorer**:
|
|
48
|
+
- a living constellation of packages and files;
|
|
49
|
+
- the flow of dependencies;
|
|
50
|
+
- the blast radius of a change;
|
|
51
|
+
- who calls what, and where the hotspots are;
|
|
52
|
+
- a guided tour, with the source one click away.
|
|
53
|
+
|
|
54
|
+
Everything is computed locally by [Ananke Plexus](https://neo-pragnya.github.io/Ananke-Plexus/), and the report is
|
|
55
|
+
a single file you can share like a PDF.
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pip install dev-guru
|
|
59
|
+
dev explore path/to/project -o explorer.html --open
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+

|
|
63
|
+
|
|
64
|
+
**[Documentation and a live demo →](https://neo-pragnya.github.io/Dev-Guru/)**: the site's hero runs the real
|
|
65
|
+
report of Dev Guru exploring its own source.
|
|
66
|
+
|
|
67
|
+
## What's in a report
|
|
68
|
+
|
|
69
|
+
| View | Question it answers |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| ✦ Constellation | What's here? Files clustered by package; hover to light up imports |
|
|
72
|
+
| ⇶ Flow | What depends on what? Entry side to foundations; cycles glow rose |
|
|
73
|
+
| ◎ Impact | What breaks if this changes? Blast-radius rings over importers and callers |
|
|
74
|
+
| ƒ Calls | Who calls in, and what goes out? A symbol-level ego network |
|
|
75
|
+
| ▦ Hotspots | Where is change expensive? A treemap of size against how depended-on a file is |
|
|
76
|
+
| ☄ Tour | Show me around: a narrated walk through the codebase |
|
|
77
|
+
|
|
78
|
+
Plus search (`/`), a command palette (`Ctrl`/`⌘` `K`), a source inspector, a light and dark theme, and shareable
|
|
79
|
+
URLs. Reports are **offline and view-only**, treat source as text, and carry a manifest with the input digest and the
|
|
80
|
+
Git revision. See [report safety](docs/concepts/report-safety.md).
|
|
81
|
+
|
|
82
|
+
## From Python
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
from dev_guru import GuruClient
|
|
86
|
+
|
|
87
|
+
with GuruClient(workspace="path/to/project") as guru:
|
|
88
|
+
result = guru.explore()
|
|
89
|
+
guru.export(result, output="explorer.html")
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## How it fits together
|
|
93
|
+
|
|
94
|
+
| Repository | Role |
|
|
95
|
+
| --- | --- |
|
|
96
|
+
| **Dev Guru** (this repo) | The product: CLI and SDK, report view models and renderers, later a local web UI |
|
|
97
|
+
| [Ananke Plexus](https://github.com/Neo-Pragnya/Ananke-Plexus) | The harness: code graph, analysis, workflows, policy, runs and evidence |
|
|
98
|
+
| [Dex Trove](https://github.com/Neo-Pragnya/Dex-Trove) | Optional capability memory: curated skills, agents, instructions and workflows |
|
|
99
|
+
|
|
100
|
+
Dev Guru never analyses code itself: every domain operation goes through one client port to Ananke, and Dex is never
|
|
101
|
+
required. See [Architecture](docs/concepts/architecture.md) and [ADR-0001](docs/decisions/0001-ananke-client-port.md).
|
|
102
|
+
|
|
103
|
+
## Quality gates
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
make verify # ruff, ruff format, strict mypy, pytest
|
|
107
|
+
make acceptance-wheel # capability scenarios on the built wheel, including real-Chrome report journeys
|
|
108
|
+
make scan # gitleaks, pip-audit, GuardDog and Bandit on dist/
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Licence
|
|
112
|
+
|
|
113
|
+
Apache-2.0. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
dev_guru/__init__.py,sha256=TxCoLblYQ_HmshasBNaWOptALxzRaAowZGszGjqhiLc,613
|
|
2
|
+
dev_guru/__main__.py,sha256=mU3UDRrVdSNQiBhkbGsThjUUewMGMK8TJj7pCuNSDY4,36
|
|
3
|
+
dev_guru/cli.py,sha256=RegHb_gDLb7cEK5FVxx1cqFJ1NGYwD4ilbI68Njag9o,5295
|
|
4
|
+
dev_guru/errors.py,sha256=AoA8VTfcXE1E-MvGdvDwVbteWhCpgfHzFyOhTygD9cA,1352
|
|
5
|
+
dev_guru/sdk.py,sha256=9wmHa_0UJ_4NlUG0vN1RriGMJaNGV7W0w37FZ4dV1UU,1520
|
|
6
|
+
dev_guru/service.py,sha256=cHvMvIsPXXYXkyA-nfy76vUSqWNYvNrkIxiPI7weoks,1734
|
|
7
|
+
dev_guru/version.py,sha256=QrWK1rkgqYP5jG0_FA_9COofxPqaIkiGR7bojyGx8lY,135
|
|
8
|
+
dev_guru/client/__init__.py,sha256=CzM_xA1E7Ux0adYrmdEhDJrG2GBkFV6K52sImocNwEE,894
|
|
9
|
+
dev_guru/client/inprocess.py,sha256=gnNX7wgywJPjcXOPDTPLH68INw95SafAocoY94LYYbI,4760
|
|
10
|
+
dev_guru/client/negotiation.py,sha256=IZDW1bJN6oMji5TP4y94dpMQR5f2wyxjOQIOfrqGo38,2388
|
|
11
|
+
dev_guru/client/port.py,sha256=wofJJckzDZUb0QZTICB0XxqqcKisyB03JfEd6duGS1M,2479
|
|
12
|
+
dev_guru/reports/__init__.py,sha256=d0GK6BrXW9UnxzfA6eEAi42LkMIyasuDqGp9rv78nIo,91
|
|
13
|
+
dev_guru/reports/model.py,sha256=RqRAICCQCIrjjYXx3M_0vYQrY20k-aHvSfKJSxA_SpE,10506
|
|
14
|
+
dev_guru/reports/render.py,sha256=-9fcRert4VY1UNalFkQXMhK4vicrdH5FVEkt-OpE4tA,5028
|
|
15
|
+
dev_guru/reports/assets/explorer.css,sha256=jprardGERDncC3A0unmfwFkQSbmONzCA3l0szdEbiY4,18572
|
|
16
|
+
dev_guru/reports/assets/explorer.html,sha256=axilH8G1uVBxPpd1rJRZ0W7tEKeFWnx4guapYGmaz7I,4909
|
|
17
|
+
dev_guru/reports/assets/explorer.js,sha256=U8ECl3fZfJDnY3gLbtEnOIoFno-Grhc3djUKWafDBR8,57806
|
|
18
|
+
dev_guru-0.1.0.dist-info/METADATA,sha256=nu2k7bDc7S7zKGBbk_pQzu3PNyvvTbJiF-XZGP1qAY4,4793
|
|
19
|
+
dev_guru-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
20
|
+
dev_guru-0.1.0.dist-info/entry_points.txt,sha256=yhnM5xcrKnHBZSg96oOqNVZUj25NOKcoYZXdg2E_foA,41
|
|
21
|
+
dev_guru-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
22
|
+
dev_guru-0.1.0.dist-info/RECORD,,
|