pymap-cli 0.3.0__tar.gz

pymap_cli-0.3.0/.gitignore

@@ -0,0 +1,26 @@
+# pymap output
+pymap-out/
+
+# Python
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# environments and caches
+.venv/
+venv/
+.tox/
+.nox/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# editor local state
+.idea/
+.vscode/
+
+# OS
+.DS_Store

pymap_cli-0.3.0/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-09-04
+
+First release prepared for publication. The codebase, its comments and the
+generated interface are now entirely in English.
+
+### Added
+- `tests/test_contract.py`, pinning the key names shared between the Python
+  payload and `templates/explorer.html`, and running `node --check` on the
+  generated script when Node is available.
+- A notice when several files share a basename, since their symbols merge into
+  one namespace in the explorer.
+- `ruff` configuration (lint + format), type annotations across the public API,
+  and a `py.typed` marker.
+- `LICENSE` (MIT), `CONTRIBUTING.md`, this changelog.
+
+### Fixed
+- A docstring containing `</script>` closed the `<script>` block early and
+  blanked the whole explorer page. Payloads now go through `script_json()`,
+  which escapes `<`, `>`, `&` and the U+2028/U+2029 line separators.
+- Keyboard navigation of the flow (<kbd>↓</kbd> <kbd>↑</kbd> <kbd>↵</kbd>) was
+  advertised in the help panel but did nothing: the step list was never filled.
+- Marking a symbol as seen (<kbd>m</kbd>) updated the progress bar but left the
+  tree unchanged; seen symbols are now dimmed and ticked.
+
+### Changed
+- Renamed for English: `Reglages` → `Settings`, `cartographier` →
+  `map_codebase`, `Rapport` → `Report`, and the modules `reglages`/`processus`/
+  `carte`/`rendu`/`analyse`/`outils`/`gabarits` → `settings`/`runner`/`mapper`/
+  `render`/`analysis`/`tools`/`templates`.
+- The call-graph JSON is now written as `calls.json` (was `appels.json`), and
+  the explorer page as `explorer.html` (was `explorateur.html`).
+
+## [0.2.0] — 2026-09-04
+
+Restructured from a single 1,339-line script into an installable package.
+
+### Added
+- `pyproject.toml`, a `src/` layout and a `pymap` console script, so pymap can
+  be installed into any Python project.
+- Zero-argument invocation: the target package is detected from
+  `[tool.pymap] target`, a `src/` layout, or the project name.
+- Configuration through `[tool.pymap]` in the target's `pyproject.toml`.
+- `--exclude`, `--editor` and `--timeout` options; code links support eight
+  editors or a custom URI template.
+- Exclusion of environments and caches (`.venv/`, `node_modules/`, `build/`, …),
+  pruned during the walk rather than after it.
+- A test suite covering the degraded path with no external tool installed.
+
+### Fixed
+- `pyreverse` was declared among the required tools and advertised in the
+  documentation, but no step ever ran it. It now produces the class and package
+  diagrams.
+- `tach` wrote a `tach.toml` two directories above the target, saving and
+  restoring any existing one — a crash in between destroyed the user's file.
+  The sources are now copied into a temporary directory.
+- External tools were not found when pymap ran from a virtualenv whose `bin/`
+  was not on `PATH`, and the `python -m` fallback failed on packages without a
+  `__main__` module.
+
+### Changed
+- The HTML templates moved out of the Python source into real `.html` files,
+  substituted through `__PYMAP_X__` tokens instead of `str.format`.
+
+## [0.1.0]
+
+Initial single-file version.

pymap_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franck Zrouama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pymap_cli-0.3.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: pymap-cli
+Version: 0.3.0
+Summary: Map a Python codebase in one command.
+Project-URL: Homepage, https://github.com/hermann225-zrouama/pymap-cli
+Project-URL: Issues, https://github.com/hermann225-zrouama/pymap-cli/issues
+Project-URL: Changelog, https://github.com/hermann225-zrouama/pymap-cli/blob/main/CHANGELOG.md
+Author: Franck Zrouama
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,ast,call graph,codebase map,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: code2flow>=2.5; extra == 'dev'
+Requires-Dist: pydeps>=1.11; extra == 'dev'
+Requires-Dist: pylint>=2.15; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tach>=0.9; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: graphs
+Requires-Dist: code2flow>=2.5; extra == 'graphs'
+Requires-Dist: pydeps>=1.11; extra == 'graphs'
+Requires-Dist: pylint>=2.15; extra == 'graphs'
+Requires-Dist: tach>=0.9; extra == 'graphs'
+Provides-Extra: toml
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'toml'
+Description-Content-Type: text/markdown
+
+# pymap
+
+Map a Python codebase in one command. No service, no upload: everything is
+analysed and rendered locally.
+
+```bash
+cd my-project
+pymap --open
+```
+
+pymap guesses which package to analyse, runs whichever graph tools you have
+installed, and assembles the result into a single page — plus a **flow
+explorer** that pymap builds itself: for every function, the order of the calls,
+the conditions, the loops, the error paths, and the data flowing through.
+
+## Install
+
+```bash
+pipx install pymap-cli          # isolated, available everywhere
+# or, inside the project you want to map:
+pip install pymap-cli
+```
+
+The core depends only on the standard library, so installing pymap into a
+project adds **no version constraint** to it. The graph tools are optional and
+live behind an extra:
+
+```bash
+pip install "pymap-cli[graphs]"     # pydeps, code2flow, pylint, tach
+brew install graphviz               # or: apt install graphviz
+```
+
+Any missing tool is reported at start-up and then skipped; the explorer always
+works.
+
+## Usage
+
+```bash
+pymap                              # guess the current project's package
+pymap src/mypkg                    # explicit target
+pymap src/mypkg -o map/ --open     # output directory, open when done
+pymap --exclude "generated_*"      # skip more paths
+pymap --editor pycharm             # code links for another editor
+```
+
+How the target is guessed, in order: `[tool.pymap] target` in `pyproject.toml`,
+a `src/<package>/` layout, the package named after the project, then the single
+top-level package. If nothing stands out, pymap says so and waits for a path.
+
+### Configuration
+
+Optional, in the project's `pyproject.toml` (read on Python ≥ 3.11, or with
+`tomli` installed):
+
+```toml
+[tool.pymap]
+target  = "src/mypkg"
+output  = "pymap-out"
+editor  = "vscode"          # vscodium, cursor, windsurf, zed, pycharm,
+                            # idea, sublime, none, or "myeditor://{f}:{l}"
+exclude = ["vendor", "generated_*"]
+timeout = 300               # seconds per external tool
+```
+
+### As a library
+
+```python
+from pymap import Settings, map_codebase
+
+report = map_codebase(Settings(target="src/mypkg", output="map/"))
+print(report.coverage, "% documented,", len(report.cycles), "cycles")
+```
+
+## What the map contains
+
+| View | Source | What you read there |
+|---|---|---|
+| **Walkthrough tree** | pymap (AST) | The execution flow function by function, keyboard-navigable |
+| Imports between modules | pydeps | The layers, and the modules everyone pulls in |
+| Classes and inheritance | pyreverse | Attributes and hierarchies, when the code is object-oriented |
+| Module boundaries | tach | File-by-file dependencies, cycles, Mermaid source |
+
+The output directory (`pymap-out/` by default) holds `index.html` — the page to
+open — and the views it links to.
+
+### In the explorer
+
+<kbd>↓</kbd> <kbd>↑</kbd> walk the steps · <kbd>↵</kbd> step into the
+highlighted call · <kbd>←</kbd> go back up · <kbd>m</kbd> mark seen ·
+<kbd>o</kbd> open in the editor · <kbd>/</kbd> search
+
+## How the code is organised
+
+```
+src/pymap/
+├── cli.py           command line: arguments, pyproject, messages
+├── settings.py      what to analyse, where to write, what to skip
+├── mapper.py        orchestration + library API
+├── runner.py        launching external tools, detecting missing ones
+├── render.py        templates → HTML pages
+├── analysis/        what pymap works out on its own, from the AST
+│   ├── symbols.py     modules, classes, functions, signatures
+│   ├── flow.py        execution tree of a function
+│   ├── calls.py       code2flow's call graph
+│   └── cycles.py      circular dependencies
+├── tools/           one module per external tool
+│   ├── pydeps.py    pyreverse.py    code2flow.py    tach.py
+└── templates/       index.html, section.html, explorer.html
+```
+
+Adding a tool: drop a module in `tools/` exposing `execute(settings)` that
+returns raw facts (never HTML), then add one line to `STEPS` and one section to
+`_sections()`, both in `mapper.py`. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Guarantees
+
+- **Nothing is executed** from the analysed code: everything goes through the
+  standard library's AST.
+- **Nothing is written** into the target project. `tach` requires a `tach.toml`
+  at the root of wherever it runs, so pymap copies the sources into a temporary
+  directory instead of dropping that file in your tree.
+- Environments and caches (`.venv/`, `node_modules/`, `build/`,
+  `__pycache__/`, …) are pruned during the walk, never traversed.
+
+## Known limitations
+
+- **Files sharing a basename share a namespace.** Symbol keys are
+  `<file stem>::<qualified name>`, because that is how code2flow names its
+  graph nodes and it is what lets the two data sets be joined. In a project
+  with `app/models.py` and `blog/models.py`, their symbols merge in the
+  explorer. pymap prints a note when it detects the case.
+- **tach declares at most 60 modules.** Beyond that `tach sync` gets very slow
+  for a graph that is already unreadable. The count left out is reported.
+- The call graph is only as good as code2flow's static resolution: calls
+  through dynamic dispatch or `getattr` do not appear.
+
+## Development
+
+```bash
+git clone https://github.com/hermann225-zrouama/pymap-cli
+cd pymap-cli
+pip install -e ".[dev]"
+pytest
+ruff check src tests && ruff format --check src tests
+pymap                  # pymap maps itself
+```
+
+`tests/test_contract.py` pins the key names shared between the Python payload
+and `templates/explorer.html`. A rename on one side without the other produces
+a blank page rather than an error, so that test is what keeps them honest.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+The distribution is named `pymap-cli` because `pymap` is already taken on PyPI
+by an IMAP library. The command and the import name are both `pymap`.

pymap_cli-0.3.0/README.md

@@ -0,0 +1,157 @@
+# pymap
+
+Map a Python codebase in one command. No service, no upload: everything is
+analysed and rendered locally.
+
+```bash
+cd my-project
+pymap --open
+```
+
+pymap guesses which package to analyse, runs whichever graph tools you have
+installed, and assembles the result into a single page — plus a **flow
+explorer** that pymap builds itself: for every function, the order of the calls,
+the conditions, the loops, the error paths, and the data flowing through.
+
+## Install
+
+```bash
+pipx install pymap-cli          # isolated, available everywhere
+# or, inside the project you want to map:
+pip install pymap-cli
+```
+
+The core depends only on the standard library, so installing pymap into a
+project adds **no version constraint** to it. The graph tools are optional and
+live behind an extra:
+
+```bash
+pip install "pymap-cli[graphs]"     # pydeps, code2flow, pylint, tach
+brew install graphviz               # or: apt install graphviz
+```
+
+Any missing tool is reported at start-up and then skipped; the explorer always
+works.
+
+## Usage
+
+```bash
+pymap                              # guess the current project's package
+pymap src/mypkg                    # explicit target
+pymap src/mypkg -o map/ --open     # output directory, open when done
+pymap --exclude "generated_*"      # skip more paths
+pymap --editor pycharm             # code links for another editor
+```
+
+How the target is guessed, in order: `[tool.pymap] target` in `pyproject.toml`,
+a `src/<package>/` layout, the package named after the project, then the single
+top-level package. If nothing stands out, pymap says so and waits for a path.
+
+### Configuration
+
+Optional, in the project's `pyproject.toml` (read on Python ≥ 3.11, or with
+`tomli` installed):
+
+```toml
+[tool.pymap]
+target  = "src/mypkg"
+output  = "pymap-out"
+editor  = "vscode"          # vscodium, cursor, windsurf, zed, pycharm,
+                            # idea, sublime, none, or "myeditor://{f}:{l}"
+exclude = ["vendor", "generated_*"]
+timeout = 300               # seconds per external tool
+```
+
+### As a library
+
+```python
+from pymap import Settings, map_codebase
+
+report = map_codebase(Settings(target="src/mypkg", output="map/"))
+print(report.coverage, "% documented,", len(report.cycles), "cycles")
+```
+
+## What the map contains
+
+| View | Source | What you read there |
+|---|---|---|
+| **Walkthrough tree** | pymap (AST) | The execution flow function by function, keyboard-navigable |
+| Imports between modules | pydeps | The layers, and the modules everyone pulls in |
+| Classes and inheritance | pyreverse | Attributes and hierarchies, when the code is object-oriented |
+| Module boundaries | tach | File-by-file dependencies, cycles, Mermaid source |
+
+The output directory (`pymap-out/` by default) holds `index.html` — the page to
+open — and the views it links to.
+
+### In the explorer
+
+<kbd>↓</kbd> <kbd>↑</kbd> walk the steps · <kbd>↵</kbd> step into the
+highlighted call · <kbd>←</kbd> go back up · <kbd>m</kbd> mark seen ·
+<kbd>o</kbd> open in the editor · <kbd>/</kbd> search
+
+## How the code is organised
+
+```
+src/pymap/
+├── cli.py           command line: arguments, pyproject, messages
+├── settings.py      what to analyse, where to write, what to skip
+├── mapper.py        orchestration + library API
+├── runner.py        launching external tools, detecting missing ones
+├── render.py        templates → HTML pages
+├── analysis/        what pymap works out on its own, from the AST
+│   ├── symbols.py     modules, classes, functions, signatures
+│   ├── flow.py        execution tree of a function
+│   ├── calls.py       code2flow's call graph
+│   └── cycles.py      circular dependencies
+├── tools/           one module per external tool
+│   ├── pydeps.py    pyreverse.py    code2flow.py    tach.py
+└── templates/       index.html, section.html, explorer.html
+```
+
+Adding a tool: drop a module in `tools/` exposing `execute(settings)` that
+returns raw facts (never HTML), then add one line to `STEPS` and one section to
+`_sections()`, both in `mapper.py`. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Guarantees
+
+- **Nothing is executed** from the analysed code: everything goes through the
+  standard library's AST.
+- **Nothing is written** into the target project. `tach` requires a `tach.toml`
+  at the root of wherever it runs, so pymap copies the sources into a temporary
+  directory instead of dropping that file in your tree.
+- Environments and caches (`.venv/`, `node_modules/`, `build/`,
+  `__pycache__/`, …) are pruned during the walk, never traversed.
+
+## Known limitations
+
+- **Files sharing a basename share a namespace.** Symbol keys are
+  `<file stem>::<qualified name>`, because that is how code2flow names its
+  graph nodes and it is what lets the two data sets be joined. In a project
+  with `app/models.py` and `blog/models.py`, their symbols merge in the
+  explorer. pymap prints a note when it detects the case.
+- **tach declares at most 60 modules.** Beyond that `tach sync` gets very slow
+  for a graph that is already unreadable. The count left out is reported.
+- The call graph is only as good as code2flow's static resolution: calls
+  through dynamic dispatch or `getattr` do not appear.
+
+## Development
+
+```bash
+git clone https://github.com/hermann225-zrouama/pymap-cli
+cd pymap-cli
+pip install -e ".[dev]"
+pytest
+ruff check src tests && ruff format --check src tests
+pymap                  # pymap maps itself
+```
+
+`tests/test_contract.py` pins the key names shared between the Python payload
+and `templates/explorer.html`. A rename on one side without the other produces
+a blank page rather than an error, so that test is what keeps them honest.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+The distribution is named `pymap-cli` because `pymap` is already taken on PyPI
+by an IMAP library. The command and the import name are both `pymap`.

pymap_cli-0.3.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# The import name and the command stay "pymap"; only the distribution name is
+# suffixed, because "pymap" is already taken on PyPI by an IMAP library.
+name = "pymap-cli"
+# Single source of truth: src/pymap/__init__.py. Bumping two files by hand is
+# how a release ends up reporting a version it was not built from.
+dynamic = ["version"]
+description = "Map a Python codebase in one command."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Franck Zrouama" }]
+keywords = ["codebase map", "documentation", "call graph", "architecture", "ast"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# The core runs on the standard library: installing pymap into a project adds
+# no version constraint to it.
+dependencies = []
+
+[project.optional-dependencies]
+# The four external tools pymap knows how to drive. Without them it still
+# produces the flow explorer.
+graphs = ["pydeps>=1.11", "code2flow>=2.5", "pylint>=2.15", "tach>=0.9"]
+toml = ["tomli>=2.0; python_version < '3.11'"]
+dev = ["pytest>=7", "ruff>=0.6", "pymap-cli[graphs,toml]"]
+
+[project.scripts]
+pymap = "pymap.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hermann225-zrouama/pymap-cli"
+Issues = "https://github.com/hermann225-zrouama/pymap-cli/issues"
+Changelog = "https://github.com/hermann225-zrouama/pymap-cli/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/pymap/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pymap"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pymap", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+# pymap maps itself: run `pymap` with no argument at the repository root.
+[tool.pymap]
+target = "src/pymap"
+output = "pymap-out"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 96
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # import sorting
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "C4",        # comprehensions
+    "SIM",       # simplify
+    "RUF",       # ruff-specific
+]
+ignore = [
+    "E501",      # line length is handled by the formatter
+    # Long lists of short words (builtin names, ignored directories) are kept as
+    # a single split() string on purpose: the literal form expands to one item
+    # per line under the formatter, and the suggested fix is a 400-column line
+    # that the formatter immediately explodes again.
+    "SIM905",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests deliberately reach into private helpers and build odd inputs.
+"tests/*" = ["B011", "SIM117"]
+"tests/sample/*" = ["D", "B", "SIM"]

pymap_cli-0.3.0/src/pymap/__init__.py

@@ -0,0 +1,37 @@
+"""pymap -- map a Python codebase in one command.
+
+It drives the tools that actually work on Python and gathers their output into
+a single page, plus a flow explorer that pymap builds itself:
+
+    pydeps      import graph between modules
+    pyreverse   class and package diagrams (ships with pylint)
+    code2flow   call graph at function level
+    tach        module graph + Mermaid, cycle detection
+
+The core depends only on the standard library: missing tools are reported and
+then skipped.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:  # imported lazily at runtime by __getattr__ below
+    from pymap.mapper import Report, map_codebase
+    from pymap.settings import Settings
+
+__version__ = "0.3.0"
+__all__ = ["Report", "Settings", "__version__", "map_codebase"]
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy import, so `import pymap` stays instant when all you want is __version__.
+    if name in ("Report", "map_codebase"):
+        from pymap import mapper
+
+        return getattr(mapper, name)
+    if name == "Settings":
+        from pymap.settings import Settings
+
+        return Settings
+    raise AttributeError(f"module 'pymap' has no attribute {name!r}")

pymap_cli-0.3.0/src/pymap/__main__.py

@@ -0,0 +1,8 @@
+"""Enables `python -m pymap`, useful when the console script is not on PATH."""
+
+import sys
+
+from pymap.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pymap_cli-0.3.0/src/pymap/analysis/__init__.py

@@ -0,0 +1 @@
+"""Static analysis: everything pymap works out on its own, without any tool."""

pymap_cli-0.3.0/src/pymap/analysis/calls.py

@@ -0,0 +1,36 @@
+"""Reading the call graph produced by code2flow."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+Relations = dict[str, dict[str, list[str]]]
+
+
+def load_call_graph(path: str | Path) -> Relations:
+    """Read code2flow's JSON and return outgoing and incoming calls per symbol.
+
+    Result shape: ``{symbol: {"calls": [...], "called_by": [...]}}``. A missing
+    or unreadable file yields an empty graph: the explorer works without it, it
+    just loses navigation between functions.
+    """
+    try:
+        graph = json.loads(Path(path).read_text(encoding="utf-8"))["graph"]
+    except (OSError, ValueError, KeyError):
+        return {}
+
+    names = {node_id: node["name"] for node_id, node in graph["nodes"].items()}
+    relations: dict[str, dict[str, set[str]]] = {}
+    for edge in graph["edges"]:
+        source, target = names.get(edge["source"]), names.get(edge["target"])
+        if not source or not target:
+            continue
+        relations.setdefault(source, {"calls": set(), "called_by": set()})["calls"].add(target)
+        relations.setdefault(target, {"calls": set(), "called_by": set()})["called_by"].add(
+            source
+        )
+    return {
+        name: {side: sorted(values) for side, values in sides.items()}
+        for name, sides in relations.items()
+    }