pragmagraph 0.0.1__py3-none-any.whl

pragmagraph/__init__.py

@@ -0,0 +1,57 @@
+"""Standalone observed-fact graph substrate for code and document structure."""
+
+from __future__ import annotations
+
+from pragmagraph.adapters import index_path
+from pragmagraph.contracts import CAPABILITIES, INDEXER_VERSION, SCHEMA_VERSION
+from pragmagraph.models import (
+    GraphEdge,
+    GraphNode,
+    GraphSnapshot,
+    HealthSummary,
+    OmittedDiagnostic,
+    PathResult,
+    PragmaGraphError,
+    QueryHit,
+    QueryRequest,
+    QueryResult,
+    SourceRef,
+)
+from pragmagraph.storage import load_snapshot, save_snapshot, stable_dumps
+
+__version__ = "0.0.1"
+
+PACKAGE_STATUS = "semantic-alpha"
+STABLE_IMPORT_ROOTS = (
+    "pragmagraph",
+    "pragmagraph.contracts",
+    "pragmagraph.models",
+    "pragmagraph.query",
+    "pragmagraph.storage",
+    "pragmagraph.adapters",
+    "pragmagraph.portability",
+)
+
+__all__ = [
+    "CAPABILITIES",
+    "GraphEdge",
+    "GraphNode",
+    "GraphSnapshot",
+    "HealthSummary",
+    "INDEXER_VERSION",
+    "OmittedDiagnostic",
+    "PACKAGE_STATUS",
+    "PathResult",
+    "PragmaGraphError",
+    "QueryHit",
+    "QueryRequest",
+    "QueryResult",
+    "SCHEMA_VERSION",
+    "STABLE_IMPORT_ROOTS",
+    "SourceRef",
+    "__version__",
+    "index_path",
+    "load_snapshot",
+    "save_snapshot",
+    "stable_dumps",
+]

pragmagraph/__main__.py

@@ -0,0 +1,123 @@
+"""CLI entrypoint for the reusable ``pragmagraph`` package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from pragmagraph import PACKAGE_STATUS, STABLE_IMPORT_ROOTS, __version__
+from pragmagraph.adapters import index_path
+from pragmagraph.models import QueryRequest
+from pragmagraph.query import health, neighborhood, path, query
+from pragmagraph.storage import load_snapshot, save_snapshot
+
+
+def smoke_payload() -> dict[str, object]:
+    """Return a deterministic package smoke payload."""
+    return {
+        "package": "pragmagraph",
+        "version": __version__,
+        "status": PACKAGE_STATUS,
+        "stable_import_roots": list(STABLE_IMPORT_ROOTS),
+        "semantic_contract": True,
+        "openminion_imports": False,
+    }
+
+
+def _print_payload(payload: object, *, as_json: bool) -> None:
+    if as_json:
+        if hasattr(payload, "to_dict"):
+            payload = payload.to_dict()
+        print(json.dumps(payload, sort_keys=True))
+        return
+    print(payload)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="pragmagraph package smoke")
+    parser.add_argument("--json", action="store_true", help="emit JSON output")
+    subparsers = parser.add_subparsers(dest="command")
+
+    index_parser = subparsers.add_parser("index", help="index a local root")
+    index_parser.add_argument("root")
+    index_parser.add_argument("--out", required=True)
+    index_parser.add_argument("--namespace", default="default")
+    index_parser.add_argument("--json", action="store_true", help="emit JSON output")
+
+    query_parser = subparsers.add_parser("query", help="query a snapshot")
+    query_parser.add_argument("snapshot")
+    query_parser.add_argument("query")
+    query_parser.add_argument("--max-results", type=int, default=10)
+    query_parser.add_argument("--json", action="store_true", help="emit JSON output")
+
+    neighborhood_parser = subparsers.add_parser(
+        "neighborhood", help="show nodes around a snapshot node"
+    )
+    neighborhood_parser.add_argument("snapshot")
+    neighborhood_parser.add_argument("node_id")
+    neighborhood_parser.add_argument("--depth", type=int, default=1)
+    neighborhood_parser.add_argument("--max-results", type=int, default=10)
+    neighborhood_parser.add_argument(
+        "--json", action="store_true", help="emit JSON output"
+    )
+
+    path_parser = subparsers.add_parser("path", help="find a bounded graph path")
+    path_parser.add_argument("snapshot")
+    path_parser.add_argument("source_id")
+    path_parser.add_argument("target_id")
+    path_parser.add_argument("--max-hops", type=int, default=4)
+    path_parser.add_argument("--json", action="store_true", help="emit JSON output")
+
+    health_parser = subparsers.add_parser("health", help="summarize a snapshot")
+    health_parser.add_argument("snapshot")
+    health_parser.add_argument("--json", action="store_true", help="emit JSON output")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "index":
+        snapshot = index_path(args.root, namespace=args.namespace)
+        save_snapshot(snapshot, args.out)
+        _print_payload(health(snapshot), as_json=args.json)
+    elif args.command == "query":
+        snapshot = load_snapshot(args.snapshot)
+        _print_payload(
+            query(
+                snapshot,
+                QueryRequest(query=args.query, max_results=args.max_results),
+            ).to_dict(),
+            as_json=True,
+        )
+    elif args.command == "neighborhood":
+        snapshot = load_snapshot(args.snapshot)
+        _print_payload(
+            neighborhood(
+                snapshot,
+                args.node_id,
+                depth=args.depth,
+                max_results=args.max_results,
+            ).to_dict(),
+            as_json=True,
+        )
+    elif args.command == "path":
+        snapshot = load_snapshot(args.snapshot)
+        _print_payload(
+            path(
+                snapshot,
+                args.source_id,
+                args.target_id,
+                max_hops=args.max_hops,
+            ).to_dict(),
+            as_json=True,
+        )
+    elif args.command == "health":
+        snapshot = load_snapshot(args.snapshot)
+        _print_payload(health(snapshot), as_json=True)
+    elif args.json:
+        print(json.dumps(smoke_payload(), sort_keys=True))
+    else:
+        print(f"pragmagraph semantic alpha OK: {smoke_payload()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pragmagraph/adapters/__init__.py

@@ -0,0 +1,378 @@
+"""Local filesystem indexer adapters for PragmaGraph."""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import re
+from pathlib import Path
+from typing import Iterable
+
+from pragmagraph.contracts import (
+    EDGE_CONTAINS,
+    EDGE_DEFINES,
+    EDGE_IMPORTS,
+    EDGE_REFERENCES_SECTION,
+    INDEXER_VERSION,
+    NODE_DIRECTORY,
+    NODE_DOC_SECTION,
+    NODE_FILE,
+    NODE_PROJECT,
+    NODE_PYTHON_SYMBOL,
+    SCHEMA_VERSION,
+)
+from pragmagraph.models import (
+    GraphEdge,
+    GraphNode,
+    GraphSnapshot,
+    OmittedDiagnostic,
+    SourceRef,
+)
+from pragmagraph.portability import edge_id, node_id, normalize_relative_path
+
+DEFAULT_IGNORES = frozenset(
+    {
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+    }
+)
+
+TEXT_SUFFIXES = frozenset({".md", ".py", ".txt", ".rst"})
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _content_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _rel(path: Path, root: Path) -> str:
+    return normalize_relative_path(path.relative_to(root))
+
+
+def _snippet(text: str, *, limit: int = 360) -> str:
+    collapsed = " ".join(text.strip().split())
+    return collapsed[:limit]
+
+
+def _markdown_slug(text: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug or "section"
+
+
+def _add_node(nodes: dict[str, GraphNode], node: GraphNode) -> None:
+    nodes.setdefault(node.id, node)
+
+
+def _add_edge(edges: dict[str, GraphEdge], edge: GraphEdge) -> None:
+    edges.setdefault(edge.id, edge)
+
+
+def _iter_paths(root: Path, ignore_names: frozenset[str]) -> Iterable[Path]:
+    for path in sorted(root.rglob("*")):
+        if any(part in ignore_names for part in path.relative_to(root).parts):
+            continue
+        yield path
+
+
+def index_path(
+    root_path: str | Path,
+    *,
+    namespace: str = "default",
+    ignore_names: frozenset[str] = DEFAULT_IGNORES,
+    created_at: str = "",
+) -> GraphSnapshot:
+    """Index a local code/docs root into a deterministic snapshot."""
+    root = Path(root_path).resolve()
+    nodes: dict[str, GraphNode] = {}
+    edges: dict[str, GraphEdge] = {}
+    omitted: list[OmittedDiagnostic] = []
+
+    project_id = node_id(namespace, NODE_PROJECT, ".")
+    _add_node(
+        nodes,
+        GraphNode(
+            id=project_id,
+            kind=NODE_PROJECT,
+            label=root.name or namespace,
+            source_ref=SourceRef(path="."),
+            metadata={"namespace": namespace},
+        ),
+    )
+
+    parent_by_path: dict[str, str] = {"": project_id}
+    for path in _iter_paths(root, ignore_names):
+        rel = _rel(path, root)
+        parent_rel = normalize_relative_path(Path(rel).parent)
+        parent_id = parent_by_path.get(parent_rel, project_id)
+        if path.is_dir():
+            current_id = node_id(namespace, NODE_DIRECTORY, rel)
+            parent_by_path[rel] = current_id
+            _add_node(
+                nodes,
+                GraphNode(
+                    id=current_id,
+                    kind=NODE_DIRECTORY,
+                    label=path.name,
+                    source_ref=SourceRef(path=rel),
+                ),
+            )
+            _add_edge(
+                edges,
+                GraphEdge(
+                    id=edge_id(namespace, parent_id, EDGE_CONTAINS, current_id),
+                    kind=EDGE_CONTAINS,
+                    source_id=parent_id,
+                    target_id=current_id,
+                    source_ref=SourceRef(path=rel),
+                ),
+            )
+            continue
+        if not path.is_file():
+            continue
+        file_id = node_id(namespace, NODE_FILE, rel)
+        text = _read_text(path) if path.suffix.lower() in TEXT_SUFFIXES else ""
+        _add_node(
+            nodes,
+            GraphNode(
+                id=file_id,
+                kind=NODE_FILE,
+                label=path.name,
+                source_ref=SourceRef(path=rel),
+                text=_snippet(text),
+                metadata={
+                    "content_hash": _content_hash(path),
+                    "suffix": path.suffix.lower(),
+                },
+            ),
+        )
+        _add_edge(
+            edges,
+            GraphEdge(
+                id=edge_id(namespace, parent_id, EDGE_CONTAINS, file_id),
+                kind=EDGE_CONTAINS,
+                source_id=parent_id,
+                target_id=file_id,
+                source_ref=SourceRef(path=rel),
+            ),
+        )
+        if path.suffix.lower() == ".md":
+            _index_markdown(
+                namespace=namespace,
+                rel=rel,
+                file_id=file_id,
+                text=text,
+                nodes=nodes,
+                edges=edges,
+            )
+        elif path.suffix.lower() == ".py":
+            _index_python(
+                namespace=namespace,
+                rel=rel,
+                file_id=file_id,
+                text=text,
+                nodes=nodes,
+                edges=edges,
+                omitted=omitted,
+            )
+
+    stats = {
+        "edge_count": len(edges),
+        "node_count": len(nodes),
+        "omitted_count": len(omitted),
+        "root_exists": root.exists(),
+    }
+    return GraphSnapshot(
+        namespace=namespace,
+        root_path=str(root),
+        nodes=tuple(sorted(nodes.values(), key=lambda node: node.id)),
+        edges=tuple(sorted(edges.values(), key=lambda edge: edge.id)),
+        omitted=tuple(omitted),
+        stats=stats,
+        schema_version=SCHEMA_VERSION,
+        indexer_version=INDEXER_VERSION,
+        created_at=created_at,
+    )
+
+
+def _index_markdown(
+    *,
+    namespace: str,
+    rel: str,
+    file_id: str,
+    text: str,
+    nodes: dict[str, GraphNode],
+    edges: dict[str, GraphEdge],
+) -> None:
+    previous_section_id = ""
+    for number, line in enumerate(text.splitlines(), start=1):
+        match = re.match(r"^(#{1,6})\s+(.+?)\s*$", line)
+        if not match:
+            continue
+        heading = match.group(2).strip()
+        slug = _markdown_slug(heading)
+        section_id = node_id(namespace, NODE_DOC_SECTION, f"{rel}#{slug}")
+        source_ref = SourceRef(path=rel, line=number, section=heading)
+        _add_node(
+            nodes,
+            GraphNode(
+                id=section_id,
+                kind=NODE_DOC_SECTION,
+                label=heading,
+                source_ref=source_ref,
+                text=heading,
+                metadata={"level": len(match.group(1)), "slug": slug},
+            ),
+        )
+        _add_edge(
+            edges,
+            GraphEdge(
+                id=edge_id(namespace, file_id, EDGE_DEFINES, section_id),
+                kind=EDGE_DEFINES,
+                source_id=file_id,
+                target_id=section_id,
+                source_ref=source_ref,
+            ),
+        )
+        if previous_section_id:
+            _add_edge(
+                edges,
+                GraphEdge(
+                    id=edge_id(
+                        namespace,
+                        previous_section_id,
+                        EDGE_REFERENCES_SECTION,
+                        section_id,
+                    ),
+                    kind=EDGE_REFERENCES_SECTION,
+                    source_id=previous_section_id,
+                    target_id=section_id,
+                    source_ref=source_ref,
+                ),
+            )
+        previous_section_id = section_id
+
+
+def _index_python(
+    *,
+    namespace: str,
+    rel: str,
+    file_id: str,
+    text: str,
+    nodes: dict[str, GraphNode],
+    edges: dict[str, GraphEdge],
+    omitted: list[OmittedDiagnostic],
+) -> None:
+    try:
+        tree = ast.parse(text)
+    except SyntaxError as exc:
+        omitted.append(
+            OmittedDiagnostic(
+                reason="python_syntax_error",
+                item_id=rel,
+                details={"line": exc.lineno, "message": exc.msg},
+            )
+        )
+        return
+
+    for item in ast.walk(tree):
+        if isinstance(item, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            symbol_key = f"{rel}:{item.name}"
+            symbol_id = node_id(namespace, NODE_PYTHON_SYMBOL, symbol_key)
+            source_ref = SourceRef(path=rel, line=getattr(item, "lineno", None))
+            _add_node(
+                nodes,
+                GraphNode(
+                    id=symbol_id,
+                    kind=NODE_PYTHON_SYMBOL,
+                    label=item.name,
+                    source_ref=source_ref,
+                    text=item.name,
+                    metadata={"symbol_type": type(item).__name__},
+                ),
+            )
+            _add_edge(
+                edges,
+                GraphEdge(
+                    id=edge_id(namespace, file_id, EDGE_DEFINES, symbol_id),
+                    kind=EDGE_DEFINES,
+                    source_id=file_id,
+                    target_id=symbol_id,
+                    source_ref=source_ref,
+                ),
+            )
+        elif isinstance(item, ast.Import):
+            for alias in item.names:
+                _add_import_edge(
+                    namespace=namespace,
+                    rel=rel,
+                    file_id=file_id,
+                    module=alias.name,
+                    line=getattr(item, "lineno", None),
+                    nodes=nodes,
+                    edges=edges,
+                )
+        elif isinstance(item, ast.ImportFrom) and item.module:
+            _add_import_edge(
+                namespace=namespace,
+                rel=rel,
+                file_id=file_id,
+                module=item.module,
+                line=getattr(item, "lineno", None),
+                nodes=nodes,
+                edges=edges,
+            )
+
+
+def _add_import_edge(
+    *,
+    namespace: str,
+    rel: str,
+    file_id: str,
+    module: str,
+    line: int | None,
+    nodes: dict[str, GraphNode],
+    edges: dict[str, GraphEdge],
+) -> None:
+    import_id = node_id(namespace, NODE_PYTHON_SYMBOL, f"import:{module}")
+    source_ref = SourceRef(path=rel, line=line)
+    _add_node(
+        nodes,
+        GraphNode(
+            id=import_id,
+            kind=NODE_PYTHON_SYMBOL,
+            label=module,
+            source_ref=SourceRef(path=rel, line=line),
+            text=module,
+            metadata={"external": True, "symbol_type": "import"},
+        ),
+    )
+    _add_edge(
+        edges,
+        GraphEdge(
+            id=edge_id(namespace, file_id, EDGE_IMPORTS, import_id),
+            kind=EDGE_IMPORTS,
+            source_id=file_id,
+            target_id=import_id,
+            source_ref=source_ref,
+        ),
+    )
+
+
+__all__ = [
+    "DEFAULT_IGNORES",
+    "TEXT_SUFFIXES",
+    "index_path",
+]

pragmagraph/contracts/__init__.py

@@ -0,0 +1,83 @@
+"""Public constants for the PragmaGraph semantic alpha contract."""
+
+from __future__ import annotations
+
+SCHEMA_VERSION = "pragmagraph.snapshot.v1alpha1"
+INDEXER_VERSION = "pragmagraph.indexer.v1alpha1"
+
+CAPABILITY_QUERY = "query"
+CAPABILITY_NEIGHBORHOOD = "neighborhood"
+CAPABILITY_PATH = "path"
+CAPABILITY_HEALTH = "health"
+CAPABILITY_REFRESH = "refresh"
+CAPABILITY_CITATIONS = "citations"
+CAPABILITY_PROVENANCE = "provenance"
+
+CAPABILITIES = frozenset(
+    {
+        CAPABILITY_QUERY,
+        CAPABILITY_NEIGHBORHOOD,
+        CAPABILITY_PATH,
+        CAPABILITY_HEALTH,
+        CAPABILITY_REFRESH,
+        CAPABILITY_CITATIONS,
+        CAPABILITY_PROVENANCE,
+    }
+)
+
+NODE_PROJECT = "project"
+NODE_DIRECTORY = "directory"
+NODE_FILE = "file"
+NODE_DOC_SECTION = "doc_section"
+NODE_PYTHON_SYMBOL = "python_symbol"
+
+NODE_KINDS = frozenset(
+    {
+        NODE_PROJECT,
+        NODE_DIRECTORY,
+        NODE_FILE,
+        NODE_DOC_SECTION,
+        NODE_PYTHON_SYMBOL,
+    }
+)
+
+EDGE_CONTAINS = "contains"
+EDGE_DEFINES = "defines"
+EDGE_IMPORTS = "imports"
+EDGE_MENTIONS = "mentions"
+EDGE_REFERENCES_SECTION = "references_section"
+
+EDGE_KINDS = frozenset(
+    {
+        EDGE_CONTAINS,
+        EDGE_DEFINES,
+        EDGE_IMPORTS,
+        EDGE_MENTIONS,
+        EDGE_REFERENCES_SECTION,
+    }
+)
+
+__all__ = [
+    "CAPABILITIES",
+    "CAPABILITY_CITATIONS",
+    "CAPABILITY_HEALTH",
+    "CAPABILITY_NEIGHBORHOOD",
+    "CAPABILITY_PATH",
+    "CAPABILITY_PROVENANCE",
+    "CAPABILITY_QUERY",
+    "CAPABILITY_REFRESH",
+    "EDGE_CONTAINS",
+    "EDGE_DEFINES",
+    "EDGE_IMPORTS",
+    "EDGE_KINDS",
+    "EDGE_MENTIONS",
+    "EDGE_REFERENCES_SECTION",
+    "INDEXER_VERSION",
+    "NODE_DIRECTORY",
+    "NODE_DOC_SECTION",
+    "NODE_FILE",
+    "NODE_KINDS",
+    "NODE_PROJECT",
+    "NODE_PYTHON_SYMBOL",
+    "SCHEMA_VERSION",
+]