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.
@@ -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,3 @@
1
+ """The package version, in a module that imports nothing (so any module can use it without an import cycle)."""
2
+
3
+ __version__ = "0.1.0"
@@ -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
+ ![Dev Guru running dev doctor and dev explore](docs/assets/dev-explore.svg)
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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ dev = dev_guru.cli:app