graphlens 0.1.1__py3-none-any.whl

graphlens/__init__.py

@@ -0,0 +1,52 @@
+"""Models, contracts, registry, and utilities for polyglot code analysis."""
+
+from graphlens.contracts import (
+    DependencyFileParser,
+    DiscoveredProject,
+    GraphBackend,
+    LanguageAdapter,
+    ProjectReader,
+    normalize_pkg_name,
+)
+from graphlens.exceptions import (
+    AdapterError,
+    AdapterNotFoundError,
+    BackendError,
+    DiscoveryError,
+    DuplicateNodeError,
+    GraphLensError,
+)
+from graphlens.models import (
+    GraphLens,
+    Node,
+    NodeKind,
+    Relation,
+    RelationKind,
+)
+from graphlens.registry import AdapterRegistry, adapter_registry
+
+__all__ = [
+    "AdapterError",
+    "AdapterNotFoundError",
+    # registry
+    "AdapterRegistry",
+    "BackendError",
+    # contracts
+    "DependencyFileParser",
+    "DiscoveredProject",
+    "DiscoveryError",
+    "DuplicateNodeError",
+    "GraphBackend",
+    # models
+    "GraphLens",
+    # exceptions
+    "GraphLensError",
+    "LanguageAdapter",
+    "Node",
+    "NodeKind",
+    "ProjectReader",
+    "Relation",
+    "RelationKind",
+    "adapter_registry",
+    "normalize_pkg_name",
+]

graphlens/contracts/__init__.py

@@ -0,0 +1,18 @@
+"""Public contracts (ABCs) for graphlens adapters and backends."""
+
+from graphlens.contracts.adapter import LanguageAdapter
+from graphlens.contracts.backend import GraphBackend
+from graphlens.contracts.deps import (
+    DependencyFileParser,
+    normalize_pkg_name,
+)
+from graphlens.contracts.reader import DiscoveredProject, ProjectReader
+
+__all__ = [
+    "DependencyFileParser",
+    "DiscoveredProject",
+    "GraphBackend",
+    "LanguageAdapter",
+    "ProjectReader",
+    "normalize_pkg_name",
+]

graphlens/contracts/adapter.py

@@ -0,0 +1,79 @@
+"""LanguageAdapter contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from graphlens.models.graph import GraphLens
+
+_EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {
+        ".venv", "venv", "__pycache__", ".git",
+        "dist", "build", ".eggs", "node_modules",
+    }
+)
+
+
+class LanguageAdapter(ABC):
+    """Contract that every language adapter package must implement."""
+
+    @abstractmethod
+    def language(self) -> str:
+        """Return the language identifier, e.g. 'python', 'typescript'."""
+        ...
+
+    @abstractmethod
+    def can_handle(self, project_root: Path) -> bool:
+        """
+        Return True if this adapter can handle the project at the given root.
+
+        Typically checks for marker files
+        (pyproject.toml, package.json, Cargo.toml).
+        """
+        ...
+
+    @abstractmethod
+    def analyze(
+        self, project_root: Path, files: list[Path] | None = None
+    ) -> GraphLens:
+        """
+        Parse the project and return a GraphLens with nodes and relations.
+
+        If ``files`` is None, the adapter collects source files itself via
+        ``collect_files()``. Pass an explicit list to override (e.g. for
+        incremental updates or custom filtering in a pipeline).
+
+        Adapters must not write to any backend — they return data only.
+        """
+        ...
+
+    def file_extensions(self) -> set[str]:
+        """
+        Return file extensions this adapter handles, e.g. {'.py'}.
+
+        Used by ``collect_files()`` for automatic discovery.
+        """
+        return set()
+
+    def collect_files(self, project_root: Path) -> list[Path]:
+        """
+        Return all source files under project_root for this adapter.
+
+        Excludes common non-source directories
+        (.venv, __pycache__, .git, etc.).
+        Override for custom discovery logic.
+        """
+        extensions = self.file_extensions()
+        if not extensions:
+            return []
+        return sorted(
+            p
+            for p in project_root.rglob("*")
+            if p.is_file()
+            and p.suffix in extensions
+            and not (_EXCLUDED_DIRS & set(p.relative_to(project_root).parts))
+        )

graphlens/contracts/backend.py

@@ -0,0 +1,27 @@
+"""GraphBackend contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from graphlens.models.graph import GraphLens
+
+
+class GraphBackend(ABC):
+    """Contract for graph persistence backends."""
+
+    @abstractmethod
+    def store(self, graph: GraphLens) -> None:
+        """
+        Persist the given graph.
+
+        Implementation decides merge/replace semantics.
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all stored data."""
+        ...

graphlens/contracts/deps.py

@@ -0,0 +1,65 @@
+"""DependencyFileParser contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class DependencyFileParser(ABC):
+    """
+    Extracts declared third-party dependency names from a project manifest.
+
+    Each implementation targets one file format (pyproject.toml, package.json,
+    requirements.txt, Cargo.toml, …).  Language adapters ship default parsers
+    for their ecosystem; users can pass custom parsers to handle non-standard
+    package managers (poetry, pnpm workspaces, pip-tools, etc.).
+
+    ``parse()`` returns *normalized* top-level distribution names so that
+    callers can compare them against the first segment of an import path::
+
+        "requests"          # PyPI
+        "scikit_learn"      # normalized: scikit-learn → scikit_learn
+        "@types/node"       # npm scoped package (keep as-is)
+
+    Normalization rule: lowercase, hyphens → underscores, drop extras/version
+    specifiers.  Scoped npm names (``@scope/pkg``) are kept unchanged.
+    """
+
+    @abstractmethod
+    def can_parse(self, project_root: Path) -> bool:
+        """Return True if this parser applies to the given project root."""
+        ...
+
+    @abstractmethod
+    def parse(self, project_root: Path) -> frozenset[str]:
+        """Return normalized top-level package names declared as deps."""
+        ...
+
+
+def normalize_pkg_name(name: str) -> str:
+    """
+    Normalize a distribution name for import-name comparison.
+
+    * Strips version specifiers and extras:
+      ``requests>=2.0 [security]`` → ``requests``
+    * Lowercases
+    * Replaces hyphens with underscores
+
+    Scoped npm names (``@scope/pkg``) are returned as-is (lowercased).
+    """
+    # Strip inline comments (requirements.txt style)
+    name = name.split("#", maxsplit=1)[0].strip()
+    # Strip extras and version specifiers: Foo[bar]>=1.0 → Foo
+    for sep in ("[", ">", "<", "=", "!", "~", ";", " "):
+        name = name.split(sep)[0]
+    name = name.strip()
+    if not name:
+        return ""
+    # Scoped npm packages keep their structure
+    if name.startswith("@"):
+        return name.lower()
+    return name.lower().replace("-", "_")

graphlens/contracts/reader.py

@@ -0,0 +1,33 @@
+"""ProjectReader contract and DiscoveredProject model."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DiscoveredProject:
+    """Result of project discovery: a root path, language, and source files."""
+
+    root: Path
+    language: str
+    files: list[Path] = field(default_factory=list)
+
+
+class ProjectReader(ABC):
+    """Contract for project discovery and source file enumeration."""
+
+    @abstractmethod
+    def discover(self, root: Path) -> list[DiscoveredProject]:
+        """
+        Scan the root directory and return discovered projects.
+
+        A monorepo may contain multiple projects (e.g., a Python backend and
+        a TypeScript frontend). Each gets its own DiscoveredProject entry.
+        """
+        ...

graphlens/exceptions.py

@@ -0,0 +1,25 @@
+"""Base exceptions for graphlens."""
+
+
+class GraphLensError(Exception):
+    """Base exception for all graphlens errors."""
+
+
+class AdapterNotFoundError(GraphLensError):
+    """No adapter found for the requested language."""
+
+
+class AdapterError(GraphLensError):
+    """Error raised during adapter execution."""
+
+
+class DuplicateNodeError(GraphLensError):
+    """A node with this ID already exists in the graph."""
+
+
+class DiscoveryError(GraphLensError):
+    """Error raised during project discovery."""
+
+
+class BackendError(GraphLensError):
+    """Error raised during graph backend operation."""

graphlens/models/__init__.py

@@ -0,0 +1,7 @@
+"""Graph model classes: GraphLens, Node, Relation, and their enums."""
+
+from graphlens.models.graph import GraphLens
+from graphlens.models.nodes import Node, NodeKind
+from graphlens.models.relations import Relation, RelationKind
+
+__all__ = ["GraphLens", "Node", "NodeKind", "Relation", "RelationKind"]

graphlens/models/graph.py

@@ -0,0 +1,41 @@
+"""In-memory code graph container."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from graphlens.exceptions import DuplicateNodeError
+
+if TYPE_CHECKING:
+    from graphlens.models.nodes import Node
+    from graphlens.models.relations import Relation
+
+
+@dataclass
+class GraphLens:
+    """Accumulator for nodes and relations produced by language adapters."""
+
+    nodes: dict[str, Node] = field(default_factory=dict)
+    relations: list[Relation] = field(default_factory=list)
+
+    def add_node(self, node: Node) -> None:
+        """Add a node; raise DuplicateNodeError on ID collision."""
+        if node.id in self.nodes:
+            msg = f"Node with id '{node.id}' already exists"
+            raise DuplicateNodeError(msg)
+        self.nodes[node.id] = node
+
+    def add_relation(self, relation: Relation) -> None:
+        """Append a relation to the graph."""
+        self.relations.append(relation)
+
+    def merge(self, other: GraphLens) -> None:
+        """
+        Merge another graph into this one.
+
+        Raises DuplicateNodeError on ID collision.
+        """
+        for node in other.nodes.values():
+            self.add_node(node)
+        self.relations.extend(other.relations)

graphlens/models/nodes.py

@@ -0,0 +1,45 @@
+"""Node (entity) model for the code graph."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from graphlens.utils.span import Span
+
+
+class NodeKind(enum.Enum):
+    """Discriminator for the kind of entity a node represents."""
+
+    PROJECT = "project"
+    MODULE = "module"
+    FILE = "file"
+    CLASS = "class"
+    FUNCTION = "function"
+    METHOD = "method"
+    PARAMETER = "parameter"
+    IMPORT = "import"
+    DEPENDENCY = "dependency"
+    SYMBOL = "symbol"
+    EXTERNAL_SYMBOL = "external_symbol"
+
+
+@dataclass(frozen=True, slots=True)
+class Node:
+    """
+    A single entity in the code graph.
+
+    Uses a kind discriminator instead of a class-per-entity hierarchy to
+    keep the model flat, serialization-friendly, and easy to produce in
+    adapter tight loops.
+    """
+
+    id: str
+    kind: NodeKind
+    qualified_name: str
+    name: str
+    file_path: str | None = None
+    span: Span | None = None
+    metadata: dict[str, object] = field(default_factory=dict)

graphlens/models/relations.py

@@ -0,0 +1,29 @@
+"""Relation (edge) model for the code graph."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+
+
+class RelationKind(enum.Enum):
+    """Discriminator for the kind of directed edge between two nodes."""
+
+    CONTAINS = "contains"
+    DECLARES = "declares"
+    IMPORTS = "imports"
+    CALLS = "calls"
+    REFERENCES = "references"
+    DEPENDS_ON = "depends_on"
+    RESOLVES_TO = "resolves_to"
+    INHERITS_FROM = "inherits_from"
+
+
+@dataclass(frozen=True, slots=True)
+class Relation:
+    """A directed edge between two nodes, referenced by ID."""
+
+    source_id: str
+    target_id: str
+    kind: RelationKind
+    metadata: dict[str, object] = field(default_factory=dict)

graphlens/registry.py

@@ -0,0 +1,76 @@
+"""Adapter registry — discovers and loads language adapters."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from typing import TYPE_CHECKING
+
+from graphlens.exceptions import AdapterNotFoundError
+
+if TYPE_CHECKING:
+    from graphlens.contracts.adapter import LanguageAdapter
+
+
+class AdapterRegistry:
+    """
+    Registry for language adapters.
+
+    Supports two registration mechanisms (in resolution order):
+    1. In-memory registration via ``register()`` — for manual setup
+       and testing.
+    2. Automatic discovery via ``importlib.metadata`` entry points
+       under the ``"graphlens.adapters"`` group — for installed
+       adapter packages.
+
+    Adapter packages register themselves in their ``pyproject.toml``::
+
+        [project.entry-points."graphlens.adapters"]
+        python = "graphlens_python:PythonAdapter"
+    """
+
+    ENTRY_POINT_GROUP = "graphlens.adapters"
+
+    def __init__(self) -> None:
+        """Initialise the registry with an empty in-memory store."""
+        self._adapters: dict[str, type[LanguageAdapter]] = {}
+
+    def register(self, name: str, adapter_cls: type[LanguageAdapter]) -> None:
+        """Register an adapter class for the given language name."""
+        self._adapters[name] = adapter_cls
+
+    def load(self, name: str) -> type[LanguageAdapter]:
+        """
+        Return the adapter class for the given language name.
+
+        Checks in-memory registry first, then entry points.
+        Raises :exc:`AdapterNotFoundError` if not found.
+        """
+        if name in self._adapters:
+            return self._adapters[name]
+
+        for ep in importlib.metadata.entry_points(
+            group=self.ENTRY_POINT_GROUP
+        ):
+            if ep.name == name:
+                adapter_cls = ep.load()
+                self._adapters[name] = adapter_cls
+                return adapter_cls
+
+        msg = (
+            f"No adapter found for language '{name}'. "
+            f"Install a graphlens-{name} package or register an adapter"
+            " manually."
+        )
+        raise AdapterNotFoundError(msg)
+
+    def available(self) -> list[str]:
+        """Return names of all available adapters (registered + entry pts)."""
+        names: set[str] = set(self._adapters)
+        for ep in importlib.metadata.entry_points(
+            group=self.ENTRY_POINT_GROUP
+        ):
+            names.add(ep.name)
+        return sorted(names)
+
+
+adapter_registry = AdapterRegistry()

graphlens/utils/__init__.py

@@ -0,0 +1,6 @@
+"""Shared utility helpers: deterministic IDs and source spans."""
+
+from graphlens.utils.ids import make_node_id
+from graphlens.utils.span import Span
+
+__all__ = ["Span", "make_node_id"]

graphlens/utils/ids.py

@@ -0,0 +1,16 @@
+"""Deterministic node ID generation."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def make_node_id(project_name: str, qualified_name: str, kind: str) -> str:
+    """
+    Return a stable, deterministic node ID.
+
+    Uses a truncated SHA-256 hex digest so the same inputs always produce
+    the same ID across runs, enabling incremental updates and graph diffing.
+    """
+    key = f"{project_name}::{kind}::{qualified_name}"
+    return hashlib.sha256(key.encode()).hexdigest()[:16]

graphlens/utils/span.py

@@ -0,0 +1,15 @@
+"""Source location utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    """A source location range. All values are 1-based."""
+
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int

graphlens-0.1.1.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.3
+Name: graphlens
+Version: 0.1.1
+Summary: Extensible polyglot code analysis framework with a graph IR
+Keywords: code-analysis,graphlens,ast,tree-sitter,static-analysis,graph,polyglot,dependency-analysis,python,code-intelligence
+Author: Neko1313
+Author-email: Neko1313 <nikita.ribalchencko@yandex.ru>
+License: MIT License
+         
+         Copyright (c) 2026 Neko1313
+         
+         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.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Dist: graphlens-python ; extra == 'python'
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/Neko1313/graphlens
+Project-URL: Issues, https://github.com/Neko1313/graphlens/issues
+Project-URL: Changelog, https://github.com/Neko1313/graphlens/blob/main/CHANGELOG.md
+Provides-Extra: python
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+  <h1>graphlens</h1>
+
+  <p>Extensible polyglot code analysis framework that parses source projects, normalizes their structure into a shared graph IR, and exposes it for dependency analysis, navigation, and code intelligence tooling.</p>
+
+  [![PyPI](https://img.shields.io/pypi/v/graphlens?color=blue)](https://pypi.org/project/graphlens/)
+  [![Python](https://img.shields.io/pypi/pyversions/graphlens)](https://pypi.org/project/graphlens/)
+  [![License](https://img.shields.io/github/license/Neko1313/graphlens)](LICENSE)
+  [![CI](https://img.shields.io/github/actions/workflow/status/Neko1313/graphlens/ci.yml?label=CI)](https://github.com/Neko1313/graphlens/actions)
+  [![codecov](https://codecov.io/gh/Neko1313/graphlens/graph/badge.svg)](https://codecov.io/gh/Neko1313/graphlens)
+
+  [Repository](https://github.com/Neko1313/graphlens) · [Issues](https://github.com/Neko1313/graphlens/issues)
+
+</div>
+
+---
+
+## Architecture
+
+```
+Repository → Language Adapter → GraphLens (IR) → Graph Backend
+```
+
+| Layer | Responsibility |
+|---|---|
+| **Language Adapter** | Parses source files, produces `GraphLens` |
+| **GraphLens** | Typed nodes + directed relations (the IR) |
+| **Graph Backend** | Persists or queries the graph (Neo4j, in-memory, …) |
+
+Adapters are **pure data producers** — they never write to any backend. The graph is the only output.
+
+## Why graph IR?
+
+- **Language-agnostic** — one shared model for Python, TypeScript, Rust, …
+- **Plugin-based adapters** — each language is a separate package, registered via Python entry points
+- **Tree-sitter powered** — all adapters use tree-sitter for error-tolerant CST parsing and exact span positions
+- **Monorepo aware** — `can_handle()` and `find_*_roots()` handle multi-language repos correctly
+- **Deterministic node IDs** — SHA-256 hash of `project::kind::qualified_name` → stable across re-scans
+
+## Installation
+
+```bash
+# Core library only (models, contracts, registry)
+pip install graphlens
+
+# Core + Python adapter
+pip install "graphlens[python]"
+```
+
+With uv:
+
+```bash
+uv add graphlens
+uv add "graphlens[python]"
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+from graphlens import adapter_registry
+
+# Load and instantiate the Python adapter
+adapter = adapter_registry.load("python")()
+
+# Analyze a project — returns a GraphLens
+graph = adapter.analyze(Path("./my-project"))
+
+print(f"Nodes:     {len(graph.nodes)}")
+print(f"Relations: {len(graph.relations)}")
+
+# Inspect nodes by kind
+from graphlens import NodeKind
+
+modules = [n for n in graph.nodes.values() if n.kind == NodeKind.MODULE]
+classes = [n for n in graph.nodes.values() if n.kind == NodeKind.CLASS]
+```
+
+## Graph model
+
+### Node kinds
+
+| Kind | Description |
+|---|---|
+| `PROJECT` | Root project node |
+| `MODULE` | Python/TS/… module (directory or file) |
+| `FILE` | Source file |
+| `CLASS` | Class declaration |
+| `FUNCTION` | Top-level function |
+| `METHOD` | Method inside a class |
+| `PARAMETER` | Function/method parameter |
+| `IMPORT` | Import statement |
+| `DEPENDENCY` | Declared package dependency |
+| `SYMBOL` | Internal symbol reference |
+| `EXTERNAL_SYMBOL` | External symbol (stdlib, third-party, unknown) |
+
+### Relation kinds
+
+| Kind | Description |
+|---|---|
+| `CONTAINS` | Structural containment (project → module → file → class) |
+| `DECLARES` | Declaration (file declares function, class declares method) |
+| `IMPORTS` | Import edge (file → import node) |
+| `RESOLVES_TO` | Import resolved to a module or external symbol |
+| `CALLS` | Function/method call |
+| `REFERENCES` | Symbol reference |
+| `INHERITS_FROM` | Class inheritance |
+| `DEPENDS_ON` | Package dependency |
+
+## Adapter plugin system
+
+Language adapters register themselves via Python entry points — no changes to the core needed:
+
+```toml
+# packages/graphlens-python/pyproject.toml
+[project.entry-points."graphlens.adapters"]
+python = "graphlens_python:PythonAdapter"
+```
+
+The registry discovers installed adapters automatically at runtime:
+
+```python
+from graphlens import adapter_registry
+
+adapter_registry.available()          # ["python", ...]
+adapter_cls = adapter_registry.load("python")
+adapter = adapter_cls()
+```
+
+Adapters can also be registered manually (useful for testing):
+
+```python
+adapter_registry.register("python", MyPythonAdapter)
+```
+
+## Implementing an adapter
+
+Subclass `LanguageAdapter` and implement four methods:
+
+```python
+from pathlib import Path
+from graphlens import GraphLens, LanguageAdapter
+
+class MyLangAdapter(LanguageAdapter):
+    def language(self) -> str:
+        return "mylang"
+
+    def file_extensions(self) -> set[str]:
+        return {".ml", ".mli"}
+
+    def can_handle(self, project_root: Path) -> bool:
+        return (project_root / "dune-project").exists()
+
+    def analyze(
+        self, project_root: Path, files: list[Path] | None = None
+    ) -> GraphLens:
+        graph = GraphLens()
+        files = files or self.collect_files(project_root)
+        # ... parse and populate graph ...
+        return graph
+```
+
+Register in `pyproject.toml` and the core registry finds it automatically.
+
+## Project structure
+
+```
+graphlens/                      ← uv workspace root (core library)
+  src/graphlens/                ← models, contracts, registry, exceptions, utils
+  packages/
+    graphlens-python/           ← Python adapter (tree-sitter)
+  tests/                         ← core tests (100% coverage)
+  examples/                      ← runnable usage examples
+```
+
+## Development
+
+Requires Python 3.13+, [uv](https://docs.astral.sh/uv/), [task](https://taskfile.dev/).
+
+```bash
+task install        # uv sync --all-groups
+task lint           # ruff + ty + bandit for all packages
+task tests          # all tests with coverage
+```
+
+Individual package tasks:
+
+```bash
+task core:lint      task core:test
+task python:lint    task python:test
+```
+
+## License
+
+MIT

graphlens-0.1.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+graphlens/__init__.py,sha256=jHL1qyi3WoUmc_cEAzrkXik4wDlWK5jfwUzlczFGwH8,1062
+graphlens/contracts/__init__.py,sha256=qBB2uUiwR_zbJfWgt6YHcg_lvaBJ1-ihioEqlINxWH8,498
+graphlens/contracts/adapter.py,sha256=o8WaJGPSlw4c4VkMpny8NjTwVyVQRbecTmHdxSuxAs4,2279
+graphlens/contracts/backend.py,sha256=ZUzQFDJ9w7jv0fxIPvZxduCSRHvRyIbemh1R8zGX_po,575
+graphlens/contracts/deps.py,sha256=qkBv1G-k9YkYZ8pjck55Ad5921BjV52sPlg4IAhF3nQ,2233
+graphlens/contracts/reader.py,sha256=-EoFjsaYBhnF894ZaqLDZRJlpaJZAGYd6eWEEu_eruk,905
+graphlens/exceptions.py,sha256=_-Dzg1if1T_oqzWYYQ05leD6C9B_0A1i4ABVoDlCQq0,596
+graphlens/models/__init__.py,sha256=--q_kvve3sbcaWaLEGQLNkPFfexSBatM9Xf7ezMn49Q,302
+graphlens/models/graph.py,sha256=BgBLcIWJAcnv9VOOTAcO_sD-Ara7lvpSSBQ8IJ_5j3Y,1258
+graphlens/models/nodes.py,sha256=am9W1IrPdrua6ay4q6vYbkL-ovN-FRMrkyb-V6Ibg6U,1070
+graphlens/models/relations.py,sha256=7rRtI3p8jZA7uxFN8R2TUXsFINu9gTT7h43GdBizVYY,710
+graphlens/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graphlens/registry.py,sha256=mjuGbMbg2yG2TiOzpEhpJOIyaRgNrlVRyO7nmu_Y3lU,2448
+graphlens/utils/__init__.py,sha256=kK7sCTawkc0mBw4WOy3GIe7HkKbCJwXT77eiqSTH3hQ,186
+graphlens/utils/ids.py,sha256=DDxJVJRC3tgt4jQ1UnHNvcC3FGJZxXZ-JjoxV3ZRSKg,493
+graphlens/utils/span.py,sha256=5D-WbcCjb5u_dVgsr0RmJ-LOM0GaM-Vu-3CixdZ9_Ig,288
+graphlens-0.1.1.dist-info/WHEEL,sha256=M4DeIjVCA49okfALADZoWX5JOGwnmHb-JOpQHtI-1c0,80
+graphlens-0.1.1.dist-info/METADATA,sha256=FcskvjnwhEXJuHHfIrAFsIl0kIzvBGTkODTE96L0_w4,8400
+graphlens-0.1.1.dist-info/RECORD,,

graphlens-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.2
+Root-Is-Purelib: true
+Tag: py3-none-any