graphyos 0.1.0__py3-none-any.whl

graphy/__init__.py

@@ -0,0 +1,38 @@
+
+from __future__ import annotations
+
+from graphy.ir import (
+    SCHEMA_VERSION,
+    Edge,
+    Evidence,
+    IRError,
+    Node,
+    Provenance,
+    Vocabulary,
+    PYTHON_AST_VOCABULARY,
+    validate_graph,
+)
+from graphy.parity import Golden, Harness, ParityError, load_golden
+from graphy.tenant import REQUIRED_FIELDS, Tenant, TenantError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Golden",
+    "Harness",
+    "ParityError",
+    "load_golden",
+    "SCHEMA_VERSION",
+    "IRError",
+    "Node",
+    "Edge",
+    "Provenance",
+    "Evidence",
+    "validate_graph",
+    "Vocabulary",
+    "PYTHON_AST_VOCABULARY",
+    "Tenant",
+    "TenantError",
+    "REQUIRED_FIELDS",
+    "__version__",
+]

graphy/__main__.py

@@ -0,0 +1,3 @@
+from graphy.cli import main
+
+raise SystemExit(main())

graphy/_portable_flock.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+try:
+    import fcntl  # type: ignore  # noqa: F401  — re-exported on POSIX
+    HAVE_FCNTL = True
+except ImportError:
+    HAVE_FCNTL = False
+
+    class _NoFcntl:
+        LOCK_EX = 2
+        LOCK_SH = 1
+        LOCK_UN = 8
+        LOCK_NB = 4
+
+        @staticmethod
+        def flock(*_args, **_kwargs) -> None:
+            return None
+
+    fcntl = _NoFcntl()  # type: ignore

graphy/_shared.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import math
+
+SUPPORT_PRIOR = 5
+
+DEFAULT_EXCLUDE = ("tests/", "test/", "docs_src/", "docs/", "scripts/", "examples/")
+
+
+def nonneg_int(v) -> int:
+    import argparse
+    i = int(v)
+    if i < 0:
+        raise argparse.ArgumentTypeError("--support-prior must be >= 0")
+    return i
+
+
+def credibility(support: int, prior: int = SUPPORT_PRIOR) -> float:
+    if support <= 0:
+        return 0.0
+    prior = max(0, prior)
+    return support / (support + prior)
+
+
+def salience(lift: float, support: int, recency: float, prior: int = SUPPORT_PRIOR) -> float:
+    return lift * credibility(support, prior) * recency
+
+
+def lift(support: int, n_a: int, n_b: int, n_commits: int) -> float:
+    return (support * n_commits) / (n_a * n_b) if (n_a and n_b and n_commits) else 0.0
+
+
+def resolve_excludes(user_exclude: str, use_defaults: bool = True) -> tuple[str, ...]:
+    user = tuple(x.strip() for x in user_exclude.split(",") if x.strip())
+    return (DEFAULT_EXCLUDE + user) if use_defaults else user
+
+
+AST_STRUCT_SALIENCE = 1.0
+AST_WIRE_SALIENCE = 5.0
+AST_WIRE_RELATIONS = {"serves", "fetches", "fetches_static", "navigates"}
+
+
+def _ast_edge_salience(relation: str) -> float:
+    return AST_WIRE_SALIENCE if relation in AST_WIRE_RELATIONS else AST_STRUCT_SALIENCE
+
+
+def _shim_adj_for_activate(unified_adj: dict) -> dict:
+    return {k: [(n, s, w) for (n, s, w, _r) in vs] for k, vs in unified_adj.items()}

graphy/adapters/__init__.py

@@ -0,0 +1,12 @@
+
+from __future__ import annotations
+
+from graphy.adapters.outline import OUTLINE_VOCABULARY, build_ir as build_outline
+from graphy.adapters.python_ast import PYTHON_AST_VOCABULARY, build_ir as build_python_ast
+
+__all__ = [
+    "PYTHON_AST_VOCABULARY",
+    "OUTLINE_VOCABULARY",
+    "build_python_ast",
+    "build_outline",
+]

graphy/adapters/outline.py

@@ -0,0 +1,76 @@
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from graphy.ir import Vocabulary
+
+__all__ = ["build_ir", "OUTLINE_VOCABULARY"]
+
+OUTLINE_VOCABULARY = Vocabulary(
+    node_types=("outline_line",),
+    edge_types=("contains",),
+    producer="outline",
+)
+
+_BULLET = re.compile(r"^[-*+]\s+(.*)$")
+_SLUG = re.compile(r"[^a-z0-9]+")
+
+
+class _NodeRecords(dict):
+
+    def __iter__(self):  # type: ignore[override]
+        return iter(self.values())
+
+
+def _slugify(label: str) -> str:
+    return (_SLUG.sub("_", label.lower()).strip("_")[:60]) or "line"
+
+
+def parse_outline(text: str, doc: str) -> list[dict]:
+    records: list[dict] = []
+    stack: list[tuple[int, str]] = []
+    seen: dict[str, int] = {}
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        body = raw.lstrip(" \t")
+        indent = len(raw[: len(raw) - len(body)].replace("\t", "    "))
+        label = body.rstrip()
+        m = _BULLET.match(label)
+        if m:
+            label = m.group(1)
+        slug = _slugify(label)
+        n = seen.get(slug, 0) + 1
+        seen[slug] = n
+        if n > 1:
+            slug = f"{slug}~{n}"
+        nid = f"outline://{doc}/{slug}"
+        while stack and stack[-1][0] >= indent:
+            stack.pop()
+        parent = stack[-1][1] if stack else None
+        stack.append((indent, nid))
+        records.append({
+            "kind": "node", "node_type": "outline_line", "id": nid,
+            "label": label, "doc": doc,
+            "dotted": f"outline.{doc}.{slug}",
+        })
+        if parent:
+            records.append({"kind": "edge", "edge_type": "contains", "src": parent, "dst": nid})
+    return records
+
+
+def build_ir(outline_file: str | Path) -> tuple[_NodeRecords, list[dict]]:
+    path = Path(outline_file)
+    text = path.read_text(encoding="utf-8")
+    doc = _slugify(path.stem)
+    nodes: _NodeRecords = _NodeRecords()
+    edges: list[dict] = []
+    for rec in parse_outline(text, doc):
+        if rec.get("kind") == "node":
+            nodes[rec["id"]] = rec
+        else:
+            edges.append(rec)
+    return nodes, edges

graphy/adapters/python_ast.py

@@ -0,0 +1,349 @@
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+from typing import Any, Iterator
+
+from graphy.ir import PYTHON_AST_VOCABULARY
+
+__all__ = ["build_ir", "walk_files", "is_package_dir", "PYTHON_AST_VOCABULARY"]
+
+_DEFAULT_EXCLUDES = (
+    "__pycache__", ".git", ".venv", "venv", "node_modules",
+    "build", "dist", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+)
+_PACKAGE_EXCLUDES = ("__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache")
+
+
+class _NodeRecords(dict):
+
+    def __iter__(self):  # type: ignore[override]
+        return iter(self.values())
+
+
+
+
+def _dotted_for(file: Path, root: Path, package: str) -> str:
+    rel = file.relative_to(root)
+    parts = list(rel.parts)
+    if parts[-1] == "__init__.py":
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1].removesuffix(".pyi").removesuffix(".py")
+    if parts == [package]:
+        return package
+    return ".".join([package] + parts) if parts else package
+
+
+def _scheme_of(dotted: str) -> str:
+    return dotted.split(".", 1)[0] if dotted else "unknown"
+
+
+def _node_id(kind: str, dotted: str) -> str:
+    return f"{_scheme_of(dotted)}://{kind}/{dotted}"
+
+
+
+
+def _expr_repr(node: ast.AST) -> str:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return f"{_expr_repr(node.value)}.{node.attr}"
+    if isinstance(node, ast.Call):
+        return _expr_repr(node.func) + "(...)"
+    try:
+        return ast.unparse(node)[:120]
+    except Exception:
+        return f"<{type(node).__name__}>"
+
+
+def _calls_in(func: ast.AST) -> Iterator[tuple[str, int]]:
+    for node in ast.walk(func):
+        if isinstance(node, ast.Call):
+            yield _expr_repr(node.func), getattr(node, "lineno", 0)
+
+
+
+
+def _resolve_module_dst(raw: str, package: str, local_packages: frozenset[str]) -> str:
+    first = raw.split(".", 1)[0]
+    if first == package:
+        return raw
+    if first in local_packages:
+        return f"{package}.{raw}"
+    return raw
+
+
+def _emit_import_edges(
+    tree: ast.AST,
+    module_id: str,
+    module_dotted: str,
+    package: str,
+    local_packages: frozenset[str],
+    is_package: bool = False,
+) -> Iterator[dict]:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                yield {
+                    "kind": "edge",
+                    "edge_type": "imports",
+                    "src": module_id,
+                    "dst": _node_id(
+                        "module",
+                        _resolve_module_dst(alias.name, package, local_packages),
+                    ),
+                    "alias": alias.asname,
+                    "line": node.lineno,
+                }
+        elif isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            if node.level:
+                drop = node.level - 1 if is_package else node.level
+                base = module_dotted.split(".")
+                base = base[: max(0, len(base) - drop)] if drop else base
+                pieces = [p for p in base + ([mod] if mod else []) if p]
+                mod = ".".join(pieces)
+            elif mod:
+                mod = _resolve_module_dst(mod, package, local_packages)
+            for alias in node.names:
+                dst = _node_id("module", mod) if mod else _node_id("module", alias.name)
+                yield {
+                    "kind": "edge",
+                    "edge_type": "imports",
+                    "src": module_id,
+                    "dst": dst,
+                    "name": alias.name,
+                    "alias": alias.asname,
+                    "line": node.lineno,
+                }
+
+
+_COMPOUND = (ast.If, ast.Try, ast.With, ast.AsyncWith, ast.For, ast.AsyncFor, ast.While)
+if hasattr(ast, "TryStar"):
+    _COMPOUND = _COMPOUND + (ast.TryStar,)
+
+
+def _defs_in(body: list) -> Iterator[ast.AST]:
+    """The def and class statements a body defines, descending through the compound statements a
+    module or class guards them with — ``if``/``else``, ``try``/``except``/``finally``, ``with``,
+    ``for``, ``while`` — and never into a function body. A version-gated backport
+    (``if hasattr(typing, X): ... else: class X``) defines X on the module; the module is its parent."""
+    for stmt in body:
+        if isinstance(stmt, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            yield stmt
+        elif isinstance(stmt, _COMPOUND):
+            yield from _defs_in(stmt.body)
+            yield from _defs_in(getattr(stmt, "orelse", []) or [])
+            for handler in getattr(stmt, "handlers", []) or []:
+                yield from _defs_in(handler.body)
+            yield from _defs_in(getattr(stmt, "finalbody", []) or [])
+
+
+def _walk_stmt(
+    stmt: ast.AST,
+    parent_id: str,
+    parent_dotted: str,
+    file_rel: str,
+    container_class: str | None = None,
+    package: str = "",
+    local_packages: frozenset[str] = frozenset(),
+) -> Iterator[dict]:
+    if isinstance(stmt, ast.ClassDef):
+        class_dotted = f"{parent_dotted}.{stmt.name}"
+        class_id = _node_id("class", class_dotted)
+        yield {
+            "kind": "node",
+            "node_type": "class",
+            "id": class_id,
+            "name": stmt.name,
+            "dotted": class_dotted,
+            "file": file_rel,
+            "line": stmt.lineno,
+            "docstring": (ast.get_docstring(stmt) or "")[:200],
+        }
+        yield {"kind": "edge", "edge_type": "contains", "src": parent_id, "dst": class_id}
+        for base in stmt.bases:
+            yield {
+                "kind": "edge",
+                "edge_type": "inherits",
+                "src": class_id,
+                "dst_repr": _expr_repr(base),
+                "line": stmt.lineno,
+            }
+        for dec in stmt.decorator_list:
+            yield {
+                "kind": "edge",
+                "edge_type": "decorates",
+                "src_repr": _expr_repr(dec),
+                "dst": class_id,
+                "line": stmt.lineno,
+            }
+        for sub in _defs_in(stmt.body):
+            yield from _walk_stmt(sub, class_id, class_dotted, file_rel,
+                                  container_class=stmt.name, package=package,
+                                  local_packages=local_packages)
+    elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        kind = "method" if container_class else "func"
+        func_dotted = f"{parent_dotted}.{stmt.name}"
+        func_id = _node_id(kind, func_dotted)
+        yield {
+            "kind": "node",
+            "node_type": kind,
+            "id": func_id,
+            "name": stmt.name,
+            "dotted": func_dotted,
+            "file": file_rel,
+            "line": stmt.lineno,
+            "is_async": isinstance(stmt, ast.AsyncFunctionDef),
+            "args": [a.arg for a in stmt.args.args],
+            "returns": _expr_repr(stmt.returns) if stmt.returns else None,
+            "docstring": (ast.get_docstring(stmt) or "")[:200],
+            "container_class": container_class,
+        }
+        yield {"kind": "edge", "edge_type": "contains", "src": parent_id, "dst": func_id}
+        for dec in stmt.decorator_list:
+            yield {
+                "kind": "edge",
+                "edge_type": "decorates",
+                "src_repr": _expr_repr(dec),
+                "dst": func_id,
+                "line": stmt.lineno,
+            }
+        for call_repr, line in _calls_in(stmt):
+            yield {
+                "kind": "edge",
+                "edge_type": "calls",
+                "src": func_id,
+                "dst_repr": call_repr,
+                "line": line,
+            }
+
+
+def _is_excluded(file: Path, exclude_patterns: tuple[str, ...], root: Path) -> bool:
+    try:
+        parts = set(file.relative_to(root).parts)
+    except ValueError:
+        parts = set(file.parts)
+    return any(p in parts for p in exclude_patterns)
+
+
+def _local_package_names(root: Path) -> frozenset[str]:
+    names: set[str] = set()
+    for entry in root.iterdir():
+        if entry.name.startswith(".") or entry.name in _DEFAULT_EXCLUDES:
+            continue
+        if entry.is_dir() and next(entry.rglob("*.py"), None) is not None:
+            names.add(entry.name)
+        elif entry.is_file() and entry.suffix == ".py":
+            names.add(entry.stem)
+    return frozenset(names)
+
+
+def _emit_raw_records_for_file(
+    file: Path,
+    root: Path,
+    package: str,
+    local_packages: frozenset[str] = frozenset(),
+    rel_base: Path | None = None,
+) -> Iterator[dict]:
+    try:
+        src = file.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return
+
+    module_dotted = _dotted_for(file, root, package)
+    module_id = _node_id("module", module_dotted)
+    file_rel = str(file.relative_to(rel_base if rel_base is not None else root.parent))
+
+    yield {
+        "kind": "node",
+        "node_type": "module",
+        "id": module_id,
+        "dotted": module_dotted,
+        "file": file_rel,
+        "loc": len(src.splitlines()),
+        "docstring": (ast.get_docstring(tree) or "")[:200],
+    }
+
+    yield from _emit_import_edges(tree, module_id, module_dotted, package,
+                                  local_packages,
+                                  is_package=file.name == "__init__.py")
+
+    for stmt in _defs_in(tree.body):
+        yield from _walk_stmt(stmt, module_id, module_dotted, file_rel,
+                              package=package, local_packages=local_packages)
+
+
+
+
+
+TEST_FILE = re.compile(r"(^|/)(tests?|testing)/|(^|/)test_[^/]*\.py$|_tests?\.py$|(^|/)conftest\.py$")
+
+
+def _emit_records_for_file(
+    file: Path,
+    root: Path,
+    package: str,
+    local_packages: frozenset[str] = frozenset(),
+    rel_base: Path | None = None,
+) -> Iterator[dict]:
+    """Every node carries ``module`` (the dotted module that holds it) and, when the producer's
+    own rule says the file is a test, ``role: test``. The consumers read those fields; no consumer
+    derives a module from a ``.py`` path or decides what a test is."""
+    module_dotted: str | None = None
+    for rec in _emit_raw_records_for_file(file, root, package, local_packages, rel_base):
+        if rec.get("kind") == "node":
+            if rec["node_type"] == "module":
+                module_dotted = rec["dotted"]
+            rec["module"] = module_dotted if module_dotted is not None else rec["dotted"]
+            if TEST_FILE.search(str(rec.get("file") or "")):
+                rec["role"] = "test"
+        yield rec
+
+def is_package_dir(corpus_dir: str | Path) -> bool:
+    """A corpus that carries its own ``__init__.py`` is one importable package: its name is the
+    scheme, its siblings are other packages. Anything else is a repo root whose top-level
+    directories are local packages that resolve under the root's name."""
+    return (Path(corpus_dir) / "__init__.py").is_file()
+
+
+def walk_files(corpus_dir: str | Path) -> list[Path]:
+    """The exact files a corpus is minted from, in mint order. A package directory skips only
+    caches; a repo root also skips build and vendored trees; a ``.py`` file is itself."""
+    root = Path(corpus_dir).resolve()
+    if root.is_file():
+        return [root] if root.suffix == ".py" else []
+    if not root.is_dir():
+        raise RuntimeError(f"path is not a directory or a .py file: {root}")
+    excludes = _PACKAGE_EXCLUDES if is_package_dir(root) else _DEFAULT_EXCLUDES
+    return [f for f in sorted(root.rglob("*.py")) if not _is_excluded(f, excludes, root)]
+
+
+def build_ir(corpus_dir: str | Path) -> tuple[_NodeRecords, list[dict]]:
+    """Mint the IR of one corpus. A directory is a package (``__init__.py`` present) or a repo
+    root; a single ``.py`` file is a one-module distribution (``typing_extensions.py``) whose
+    scheme is the file's stem. Files are named relative to the corpus's parent."""
+    root = Path(corpus_dir).resolve()
+    nodes: _NodeRecords = _NodeRecords()
+    edges: list[dict] = []
+    if root.is_file() and root.suffix == ".py":
+        package, base, local_packages = root.stem, root.parent, frozenset()
+    else:
+        package, base = root.name, root
+        local_packages = frozenset() if is_package_dir(root) else _local_package_names(root)
+    for file in walk_files(root):
+        for rec in _emit_records_for_file(file, base, package, local_packages=local_packages,
+                                          rel_base=base.parent if root.is_dir() else base):
+            if rec.get("kind") == "node":
+                nodes[rec["id"]] = rec
+            else:
+                edges.append(rec)
+    return nodes, edges