entrygraph 0.1.2__tar.gz → 0.1.3__tar.gz

entrygraph-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+# One job per quality gate. main is covered by release.yml's own test gate, so
+# it's excluded here to avoid duplicate runs.
+on:
+  pull_request: {}
+  push:
+    branches-ignore: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - name: ruff format --check
+        run: uv run --extra dev ruff format --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - name: ruff check
+        run: uv run --extra dev ruff check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - name: mypy
+        run: uv run --extra dev mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: pytest + coverage
+        run: uv run --extra dev pytest -q --cov=entrygraph --cov-report=term-missing
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - name: bandit
+        run: uv run --extra dev bandit -c pyproject.toml -r src/entrygraph -q
+
+  mdformat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+      - name: mdformat --check
+        run: uv run --extra dev mdformat --check $(git ls-files '*.md')

{entrygraph-0.1.2 → entrygraph-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entrygraph
-Version: 0.1.2
+Version: 0.1.3
 Summary: Language-agnostic code graph: query symbols, entrypoints, and source-to-sink call paths from a SQLite index
 Project-URL: Repository, https://github.com/brettbergin/entrygraph
 Author-email: Brett Bergin <brettberginbc@yahoo.com>
@@ -40,8 +40,13 @@ Requires-Dist: sqlalchemy<3.0,>=2.0.30
 Requires-Dist: tree-sitter-language-pack>=1.10
 Requires-Dist: tree-sitter<0.26,>=0.25
 Provides-Extra: dev
+Requires-Dist: bandit>=1.7; extra == 'dev'
+Requires-Dist: mdformat-gfm>=0.3; extra == 'dev'
+Requires-Dist: mdformat>=0.7; extra == 'dev'
+Requires-Dist: mypy<2,>=1.11; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # entrygraph
@@ -304,20 +309,20 @@ results are safe to hold and trivial to serialize.
 1. **Walk** — `os.scandir` with hard-pruned junk dirs (`node_modules`, `.venv`,
    …), `.gitignore` rules, and size/binary/minified gates. Every skip is recorded
    with a reason.
-2. **Extract** — tree-sitter `.scm` queries harvest definitions/imports/calls;
+1. **Extract** — tree-sitter `.scm` queries harvest definitions/imports/calls;
    small per-language "shaper" modules build qualified names, import maps, and
    receiver info. Parsing runs across a process pool for large repos.
-3. **Resolve** — a two-pass resolver binds references to symbols with a
+1. **Resolve** — a two-pass resolver binds references to symbols with a
    confidence level (`exact` / `import` / `fuzzy` / `unresolved`). External
    callees (`subprocess.run`, `child_process.exec`, …) become placeholder nodes
    so sinks are real graph terminals.
-4. **Detect** — frameworks are scored from manifest dependencies plus code
+1. **Detect** — frameworks are scored from manifest dependencies plus code
    signals (noisy-or); entrypoint rules map framework patterns to route/command
    records.
-5. **Store** — everything persists to SQLite via the SQLAlchemy 2.0 ORM with
+1. **Store** — everything persists to SQLite via the SQLAlchemy 2.0 ORM with
    bulk inserts and app-assigned keys. Re-indexing is incremental and
    content-hash driven.
-6. **Query** — reachability runs over an in-memory adjacency cache (BFS/DFS with
+1. **Query** — reachability runs over an in-memory adjacency cache (BFS/DFS with
    cycle handling); a recursive-CTE SQL engine is available as a fallback
    (`engine="sql"`).
 

{entrygraph-0.1.2 → entrygraph-0.1.3}/README.md

@@ -258,20 +258,20 @@ results are safe to hold and trivial to serialize.
 1. **Walk** — `os.scandir` with hard-pruned junk dirs (`node_modules`, `.venv`,
    …), `.gitignore` rules, and size/binary/minified gates. Every skip is recorded
    with a reason.
-2. **Extract** — tree-sitter `.scm` queries harvest definitions/imports/calls;
+1. **Extract** — tree-sitter `.scm` queries harvest definitions/imports/calls;
    small per-language "shaper" modules build qualified names, import maps, and
    receiver info. Parsing runs across a process pool for large repos.
-3. **Resolve** — a two-pass resolver binds references to symbols with a
+1. **Resolve** — a two-pass resolver binds references to symbols with a
    confidence level (`exact` / `import` / `fuzzy` / `unresolved`). External
    callees (`subprocess.run`, `child_process.exec`, …) become placeholder nodes
    so sinks are real graph terminals.
-4. **Detect** — frameworks are scored from manifest dependencies plus code
+1. **Detect** — frameworks are scored from manifest dependencies plus code
    signals (noisy-or); entrypoint rules map framework patterns to route/command
    records.
-5. **Store** — everything persists to SQLite via the SQLAlchemy 2.0 ORM with
+1. **Store** — everything persists to SQLite via the SQLAlchemy 2.0 ORM with
    bulk inserts and app-assigned keys. Re-indexing is incremental and
    content-hash driven.
-6. **Query** — reachability runs over an in-memory adjacency cache (BFS/DFS with
+1. **Query** — reachability runs over an in-memory adjacency cache (BFS/DFS with
    cycle handling); a recursive-CTE SQL engine is available as a fallback
    (`engine="sql"`).
 

{entrygraph-0.1.2 → entrygraph-0.1.3}/RELEASING.md

@@ -7,12 +7,12 @@ PyPI — no manual version edits, no tokens.
 ## How it works
 
 1. A merge lands on `main` → [`.github/workflows/release.yml`](.github/workflows/release.yml) runs.
-2. The test suite must pass (gate).
-3. The workflow finds the latest `vX.Y.Z` tag and computes the next **patch**
+1. The test suite must pass (gate).
+1. The workflow finds the latest `vX.Y.Z` tag and computes the next **patch**
    version (`v0.1.4` → `v0.1.5`). With no tags yet, the first release is `v0.1.0`.
-4. It creates and pushes that tag. [`hatch-vcs`](https://github.com/ofek/hatch-vcs)
+1. It creates and pushes that tag. [`hatch-vcs`](https://github.com/ofek/hatch-vcs)
    derives the package version from the tag, so nothing is committed back to `main`.
-5. `uv build` produces the sdist + wheel, which are published to PyPI via
+1. `uv build` produces the sdist + wheel, which are published to PyPI via
    **Trusted Publishing (OIDC)** and attached to a GitHub Release.
 
 Pull requests are tested separately by [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
@@ -26,15 +26,15 @@ This lets GitHub Actions publish without an API token. Because the project
 doesn't exist on PyPI yet, add it as a **pending** publisher:
 
 1. Log in to PyPI → <https://pypi.org/manage/account/publishing/>.
-2. Under "Add a new pending publisher", enter:
-   | Field | Value |
-   | --- | --- |
-   | PyPI Project Name | `entrygraph` |
-   | Owner | `brettbergin` |
-   | Repository name | `entrygraph` |
-   | Workflow name | `release.yml` |
-   | Environment name | *(leave blank)* |
-3. Save. The first successful run creates the project and binds the publisher.
+1. Under "Add a new pending publisher", enter:
+   | Field             | Value           |
+   | ----------------- | --------------- |
+   | PyPI Project Name | `entrygraph`    |
+   | Owner             | `brettbergin`   |
+   | Repository name   | `entrygraph`    |
+   | Workflow name     | `release.yml`   |
+   | Environment name  | *(leave blank)* |
+1. Save. The first successful run creates the project and binds the publisher.
 
 > The PyPI project name `entrygraph` must be available (or already owned by you).
 > If it's taken, rename the project in `pyproject.toml` before the first release.

{entrygraph-0.1.2 → entrygraph-0.1.3}/pyproject.toml

@@ -28,7 +28,17 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0", "pytest-cov"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+    "ruff>=0.15",
+    # mypy 2.x needs pathspec>=1.0 (imports pathspec.patterns.gitignore), which
+    # conflicts with our runtime pin pathspec<1.0; 1.x is compatible.
+    "mypy>=1.11,<2",
+    "bandit>=1.7",
+    "mdformat>=0.7",
+    "mdformat-gfm>=0.3",
+]
 
 [project.scripts]
 entrygraph = "entrygraph.cli.main:main"
@@ -54,3 +64,36 @@ packages = ["src/entrygraph"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 markers = ["slow: performance guardrail tests (deselect with '-m \"not slow\"')"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+extend-exclude = ["src/entrygraph/_version.py"]
+
+[tool.ruff.lint]
+# pyflakes, pycodestyle, isort, pyupgrade, bugbear, comprehensions, simplify
+select = ["F", "E", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = [
+    "SIM105",  # contextlib.suppress over try/except/pass — try/except is clearer here
+    "B905",    # zip() without strict= — fine for equal-length paired iterables
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011", "E402", "SIM"]  # tests: allow assert False, late imports, verbose forms
+# B023: the DFS helper closes over loop-scoped stack/on_path but is invoked
+# synchronously within the same iteration, so the late-binding concern is moot.
+"src/entrygraph/graph/adjacency.py" = ["B023"]
+
+[tool.mypy]
+python_version = "3.13"
+mypy_path = "src"
+packages = ["entrygraph"]
+ignore_missing_imports = true   # tree-sitter, sqlalchemy internals, etc. ship partial stubs
+exclude = ["_version\\.py$"]
+
+[tool.bandit]
+# Scan library code only; tests/fixtures contain deliberately vulnerable sample apps.
+exclude_dirs = ["tests", "src/entrygraph/_version.py"]
+# B314/B405: ElementTree parses local project manifests (pom.xml/.csproj) the user is
+# already indexing — not attacker-controlled network XML, so XXE risk is not applicable.
+skips = ["B314", "B405"]

{entrygraph-0.1.2 → entrygraph-0.1.3}/src/entrygraph/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.1.3'
+__version_tuple__ = version_tuple = (0, 1, 3)
 
 __commit_id__ = commit_id = None

{entrygraph-0.1.2 → entrygraph-0.1.3}/src/entrygraph/api.py

@@ -8,8 +8,8 @@ frozen dataclasses; the Session never escapes (except via the explicit
 from __future__ import annotations
 
 import json
+from collections.abc import Iterator
 from pathlib import Path
-from typing import Iterator
 
 from sqlalchemy import Engine, func, select, text
 from sqlalchemy.orm import Session
@@ -23,7 +23,7 @@ from entrygraph.errors import (
     RepositoryNotIndexedError,
     SymbolNotFoundError,
 )
-from entrygraph.graph.adjacency import AdjacencyCache, Hop
+from entrygraph.graph.adjacency import AdjacencyCache
 from entrygraph.graph.scoring import is_constant_args, score_path
 from entrygraph.kinds import Confidence
 from entrygraph.results import (
@@ -42,7 +42,7 @@ from entrygraph.results import (
 
 DEFAULT_DB_NAME = ".entrygraph.db"
 
-SourceSpec = "str | Symbol | Entrypoint | list[str | Symbol | Entrypoint]"
+type SourceSpec = str | Symbol | Entrypoint | list[str | Symbol | Entrypoint]
 
 
 def _traversal_params(
@@ -76,11 +76,12 @@ class CodeGraph:
         self._engine = engine
         self._session_factory = make_session_factory(engine)
         self._adjacency: dict[tuple[frozenset[str], int], AdjacencyCache] = {}
+        self._last_index_stats: IndexStats | None = None
 
     # ---------------- construction ----------------
 
     @classmethod
-    def index(cls, root: str | Path, db: str | Path | None = None) -> "CodeGraph":
+    def index(cls, root: str | Path, db: str | Path | None = None) -> CodeGraph:
         """Index (or fully re-index) a repository and return an open graph."""
         from entrygraph.pipeline.scanner import index_repository
 
@@ -92,7 +93,7 @@ class CodeGraph:
         return graph
 
     @classmethod
-    def open(cls, db: str | Path) -> "CodeGraph":
+    def open(cls, db: str | Path) -> CodeGraph:
         db_path = Path(db)
         if not db_path.exists():
             raise DatabaseNotFoundError(f"no index database at {db_path}")
@@ -103,7 +104,7 @@ class CodeGraph:
     def close(self) -> None:
         self._engine.dispose()
 
-    def __enter__(self) -> "CodeGraph":
+    def __enter__(self) -> CodeGraph:
         return self
 
     def __exit__(self, *exc) -> None:
@@ -124,8 +125,14 @@ class CodeGraph:
     ) -> list[Symbol]:
         with self._session_factory() as session:
             return q.select_symbols(
-                session, kind=kind, name=name, qname=qname, file=file,
-                include_external=include_external, limit=limit, offset=offset,
+                session,
+                kind=kind,
+                name=name,
+                qname=qname,
+                file=file,
+                include_external=include_external,
+                limit=limit,
+                offset=offset,
             )
 
     def symbol(self, qname: str) -> Symbol:
@@ -152,9 +159,13 @@ class CodeGraph:
 
     def detect(self) -> DetectionReport:
         with self._session_factory() as session:
-            rows = session.execute(
-                select(models.Detection).order_by(models.Detection.confidence.desc())
-            ).scalars().all()
+            rows = (
+                session.execute(
+                    select(models.Detection).order_by(models.Detection.confidence.desc())
+                )
+                .scalars()
+                .all()
+            )
         languages = []
         frameworks = []
         for row in rows:
@@ -177,7 +188,7 @@ class CodeGraph:
                         evidence=tuple(evidence.get("signals", [])),
                     )
                 )
-        languages.sort(key=lambda l: l.byte_count, reverse=True)
+        languages.sort(key=lambda lang: lang.byte_count, reverse=True)
         return DetectionReport(languages=tuple(languages), frameworks=tuple(frameworks))
 
     # ---------------- entrypoints ----------------
@@ -197,23 +208,27 @@ class CodeGraph:
 
     # ---------------- traversal ----------------
 
-    def callers(self, target: "SourceSpec", *, depth: int = 1,
-                edge_kinds: tuple[str, ...] = ("calls",)) -> list[Symbol]:
+    def callers(
+        self, target: SourceSpec, *, depth: int = 1, edge_kinds: tuple[str, ...] = ("calls",)
+    ) -> list[Symbol]:
         return self._neighbors(target, depth, "in", edge_kinds)
 
-    def callees(self, target: "SourceSpec", *, depth: int = 1,
-                edge_kinds: tuple[str, ...] = ("calls",)) -> list[Symbol]:
+    def callees(
+        self, target: SourceSpec, *, depth: int = 1, edge_kinds: tuple[str, ...] = ("calls",)
+    ) -> list[Symbol]:
         return self._neighbors(target, depth, "out", edge_kinds)
 
-    def references(self, target: "SourceSpec") -> list[Edge]:
+    def references(self, target: SourceSpec) -> list[Edge]:
         """All inbound edges (any kind) to the matching symbols."""
         with self._session_factory() as session:
             ids = self._spec_to_ids(session, target)
             if not ids:
                 return []
-            rows = session.execute(
-                select(models.Edge).where(models.Edge.dst_symbol_id.in_(ids))
-            ).scalars().all()
+            rows = (
+                session.execute(select(models.Edge).where(models.Edge.dst_symbol_id.in_(ids)))
+                .scalars()
+                .all()
+            )
             src_map = q.symbols_by_ids(session, {r.src_symbol_id for r in rows})
             return [
                 Edge(
@@ -236,8 +251,8 @@ class CodeGraph:
     def paths(
         self,
         *,
-        source: "SourceSpec",
-        sink: "SourceSpec | None" = None,
+        source: SourceSpec,
+        sink: SourceSpec | None = None,
         sink_category: str | None = None,
         max_depth: int = 25,
         max_paths: int = 10,
@@ -282,15 +297,16 @@ class CodeGraph:
                 for path in raw_paths
             ]
         results = [cp for cp in built if not (prune_sanitized and _fully_sanitized(cp))]
-        results.sort(key=lambda p: (-(p.risk_score or 0.0), len(p.symbols),
-                                    [s.id for s in p.symbols]))
+        results.sort(
+            key=lambda p: (-(p.risk_score or 0.0), len(p.symbols), [s.id for s in p.symbols])
+        )
         return results
 
     def reachable(
         self,
         *,
-        source: "SourceSpec",
-        sink: "SourceSpec | None" = None,
+        source: SourceSpec,
+        sink: SourceSpec | None = None,
         sink_category: str | None = None,
         max_depth: int = 25,
         edge_kinds: tuple[str, ...] = ("calls",),
@@ -320,8 +336,7 @@ class CodeGraph:
             repo = session.execute(select(models.Repository)).scalars().first()
         if repo is None:
             raise RepositoryNotIndexedError("database has no indexed repository")
-        stats = index_repository(repo.root_path, self._engine, incremental=True,
-                                 paranoid=paranoid)
+        stats = index_repository(repo.root_path, self._engine, incremental=True, paranoid=paranoid)
         self._adjacency.clear()
         return stats
 
@@ -341,9 +356,7 @@ class CodeGraph:
                 symbols=count(select(func.count(models.Symbol.id))),
                 edges=count(select(func.count(models.Edge.id))),
                 resolved_edges=count(
-                    select(func.count(models.Edge.id)).where(
-                        models.Edge.dst_symbol_id.is_not(None)
-                    )
+                    select(func.count(models.Edge.id)).where(models.Edge.dst_symbol_id.is_not(None))
                 ),
                 entrypoints=count(select(func.count(models.Entrypoint.id))),
                 sink_edges=count(
@@ -366,8 +379,14 @@ class CodeGraph:
         gen = session.execute(select(models.Repository.index_generation)).scalar()
         return gen or 0
 
-    def _traverser(self, session: Session, engine: str, edge_kinds: tuple[str, ...],
-                min_confidence: int, include_cha: bool = True):
+    def _traverser(
+        self,
+        session: Session,
+        engine: str,
+        edge_kinds: tuple[str, ...],
+        min_confidence: int,
+        include_cha: bool = True,
+    ):
         if engine == "sql":
             from entrygraph.graph.cte import CteEngine
 
@@ -376,8 +395,13 @@ class CodeGraph:
             raise ValueError(f"unknown reachability engine {engine!r} (use 'memory' or 'sql')")
         return self._cache(session, edge_kinds, min_confidence, include_cha)
 
-    def _cache(self, session: Session, edge_kinds: tuple[str, ...],
-               min_confidence: int, include_cha: bool = True) -> AdjacencyCache:
+    def _cache(
+        self,
+        session: Session,
+        edge_kinds: tuple[str, ...],
+        min_confidence: int,
+        include_cha: bool = True,
+    ) -> AdjacencyCache:
         kinds = frozenset(edge_kinds)
         generation = self._generation(session)
         key = (kinds | {f"minconf:{min_confidence}", f"cha:{include_cha}"}, generation)
@@ -417,11 +441,12 @@ class CodeGraph:
                         models.Edge.dst_symbol_id.is_not(None),
                     )
                 ).scalars()
-                ids |= set(rows)
+                ids |= {r for r in rows if r is not None}
         return ids
 
-    def _neighbors(self, target, depth: int, direction: str,
-                   edge_kinds: tuple[str, ...]) -> list[Symbol]:
+    def _neighbors(
+        self, target, depth: int, direction: str, edge_kinds: tuple[str, ...]
+    ) -> list[Symbol]:
         with self._session_factory() as session:
             ids = self._spec_to_ids(session, target)
             if not ids:
@@ -438,13 +463,13 @@ class CodeGraph:
         return registry_for_repo(repo.root_path if repo else None)
 
     @staticmethod
-    def _edge_rows(session: Session, raw_paths) -> dict[int, "models.Edge"]:
+    def _edge_rows(session: Session, raw_paths) -> dict[int, models.Edge]:
         edge_ids = {hop.edge_id for path in raw_paths for _, hop in path if hop and hop.edge_id}
         if not edge_ids:
             return {}
-        rows = session.execute(
-            select(models.Edge).where(models.Edge.id.in_(edge_ids))
-        ).scalars().all()
+        rows = (
+            session.execute(select(models.Edge).where(models.Edge.id.in_(edge_ids))).scalars().all()
+        )
         return {r.id: r for r in rows}
 
     @staticmethod
@@ -522,15 +547,16 @@ class CodeGraph:
 
         risk = score_path(
             hop_confidences=[h.confidence for h in hops],
-            hop_vias=[(rows[i].via if rows[i] else h.via) for i, h in enumerate(hops)],
+            hop_vias=[(row.via if row is not None else h.via) for row, h in zip(rows, hops)],
             sink_severity=registry.severity_of(sink_id),
             sanitized_effect=sanitized_effect,
             constant_args=terminal_const,
             source_tainted=path[0][0] in tainted_sources,
         )
         may_continue = any(node in excluded_nodes for node, _ in path)
-        return CallPath(symbols=symbols, edges=tuple(path_edges),
-                        risk_score=risk, may_continue=may_continue)
+        return CallPath(
+            symbols=symbols, edges=tuple(path_edges), risk_score=risk, may_continue=may_continue
+        )
 
     @staticmethod
     def _path_sanitizers(symbols, rows, registry, sink_category):