graphlens 0.1.1__tar.gz

graphlens-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+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.

graphlens-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,196 @@
+<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/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "graphlens"
+version = "0.1.1"
+description = "Extensible polyglot code analysis framework with a graph IR"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+authors = [
+    { name = "Neko1313", email = "nikita.ribalchencko@yandex.ru" }
+]
+keywords = [
+    "code-analysis",
+    "graphlens",
+    "ast",
+    "tree-sitter",
+    "static-analysis",
+    "graph",
+    "polyglot",
+    "dependency-analysis",
+    "python",
+    "code-intelligence",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/Neko1313/graphlens"
+Issues = "https://github.com/Neko1313/graphlens/issues"
+Changelog = "https://github.com/Neko1313/graphlens/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[project.optional-dependencies]
+python = [
+    "graphlens-python"
+]
+
+[dependency-groups]
+lint = [
+    "bandit>=1.9.3",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
+]
+test = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "httpx>=0.28.0",
+]
+
+[tool.uv.sources]
+graphlens-python = { workspace = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "packages/graphlens-python/tests"]
+
+[tool.coverage.run]
+source = ["graphlens", "graphlens_python"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

graphlens-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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