langgraph-lint 0.1.0__py3-none-any.whl

langgraph_lint/__init__.py

@@ -0,0 +1,13 @@
+"""Public API.
+
+Find LangGraph wiring bugs LangGraph itself won't catch until runtime.
+"""
+
+from __future__ import annotations
+
+from langgraph_lint.core import lint
+from langgraph_lint.models import Finding, Severity
+
+__version__ = "0.1.0"
+
+__all__ = ["Finding", "Severity", "__version__", "lint"]

langgraph_lint/cli.py

@@ -0,0 +1,111 @@
+"""Command-line interface.
+
+Loads a graph object out of your own code, the same way ``uvicorn`` or
+``gunicorn`` load an ASGI app: ``module.path:attribute``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+
+from langgraph_lint import __version__, lint
+from langgraph_lint.models import Finding, Severity
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+
+def _load_target(spec: str) -> object:
+    """Resolve ``"pkg.module:attribute"`` into the live object it names."""
+    if ":" not in spec:
+        raise ValueError(
+            f"target must be 'module.path:attribute', e.g. 'myapp.graph:app'; got {spec!r}"
+        )
+    module_name, _, attr_path = spec.partition(":")
+    sys.path.insert(0, str(Path.cwd()))
+    module = importlib.import_module(module_name)
+    obj: object = module
+    for part in attr_path.split("."):
+        obj = getattr(obj, part)
+    return obj
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="langgraph-lint",
+        description="Find LangGraph wiring bugs before they become a runtime KeyError.",
+    )
+    parser.add_argument(
+        "target",
+        nargs="?",
+        help="graph to check, as 'module.path:attribute' (e.g. 'myapp.graph:app')",
+    )
+    parser.add_argument(
+        "--min-severity",
+        choices=[s.value for s in Severity],
+        default="medium",
+        help="minimum severity to report (default: medium)",
+    )
+    parser.add_argument("--format", choices=["text", "json", "github"], default="text")
+    parser.add_argument("--exit-zero", action="store_true", help="always exit 0")
+    parser.add_argument("--version", action="version", version=f"langgraph-lint {__version__}")
+    return parser
+
+
+def _print_text(findings: list[Finding], target: str) -> None:
+    if not findings:
+        print(f"{target}: no findings. Every node earns its wiring.")
+        return
+    for finding in findings:
+        print(f"  {finding}")
+        if finding.caveat:
+            print(f"    ? {finding.caveat}")
+    print(f"\n{len(findings)} finding(s) in {target}.")
+
+
+def _print_github(findings: list[Finding]) -> None:
+    for f in findings:
+        level = "error" if f.severity == Severity.HIGH else "warning"
+        print(f"::{level} title={f.rule}::{f.node}: {f.message}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if not args.target:
+        _build_parser().print_help()
+        return EXIT_ERROR
+
+    try:
+        graph_like = _load_target(args.target)
+    except (ValueError, ImportError, AttributeError) as exc:
+        print(f"langgraph-lint: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+    try:
+        findings = lint(graph_like)
+    except TypeError as exc:
+        print(f"langgraph-lint: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+    threshold = {"high": 0, "medium": 1, "low": 2}[args.min_severity]
+    findings = [f for f in findings if {"high": 0, "medium": 1, "low": 2}[f.severity] <= threshold]
+
+    if args.format == "json":
+        print(json.dumps([f.as_dict() for f in findings], indent=2))
+    elif args.format == "github":
+        _print_github(findings)
+    else:
+        _print_text(findings, args.target)
+
+    if args.exit_zero:
+        return EXIT_OK
+    return EXIT_FINDINGS if findings else EXIT_OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

langgraph_lint/core.py

@@ -0,0 +1,302 @@
+"""Structural analysis of a LangGraph (or plain LangChain Runnable) graph.
+
+Works by duck-typing against whatever ``.get_graph()`` returns -- a
+``langchain_core.runnables.graph.Graph`` with ``.nodes`` and ``.edges``. This
+module never imports ``langgraph`` or ``langchain_core``, so it has zero
+required dependencies; it only needs an object shaped like the ones those
+libraries produce.
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+import typing
+from collections import defaultdict, deque
+from typing import Any
+
+from langgraph_lint.models import Finding, Severity
+
+#: LangGraph's reserved entry/exit node ids. Hardcoded rather than imported
+#: from ``langgraph.graph`` to keep this module dependency-free; stable across
+#: the versions this was built and tested against.
+START = "__start__"
+END = "__end__"
+
+
+def lint(graph_like: Any) -> list[Finding]:
+    """Analyze a graph for wiring defects LangGraph itself won't catch.
+
+    Args:
+        graph_like: A compiled LangGraph graph, an uncompiled
+            ``StateGraph``/``Graph`` builder, or any object exposing
+            ``.get_graph()`` -> an object with ``.nodes`` and ``.edges``
+            (this is exactly what ``langchain_core.runnables.graph.Graph``
+            looks like, so plain LCEL runnables work too).
+
+    Returns:
+        Findings sorted by severity, then rule, then node name.
+    """
+    nodes, edges, branches, compile_error = _resolve(graph_like)
+    findings: list[Finding] = []
+
+    if compile_error is not None:
+        findings.append(
+            Finding(
+                rule="LG000",
+                node="<graph>",
+                message=f"graph does not compile: {compile_error}",
+                severity=Severity.HIGH,
+                caveat="",
+            )
+        )
+        return findings
+
+    forward: dict[str, set[str]] = defaultdict(set)
+    for edge in edges:
+        forward[edge.source].add(edge.target)
+
+    send_targets = _send_targets(nodes, branches)
+    reachable = _bfs(START, forward)
+
+    for name in nodes:
+        if name in (START, END):
+            continue
+        if name not in reachable:
+            findings.append(_unreachable_finding(name, send_targets))
+
+    if branches:
+        findings.extend(_check_conditional_branches(branches, nodes))
+
+    return sorted(
+        findings,
+        key=lambda f: ({"high": 0, "medium": 1, "low": 2}[f.severity], f.rule, f.node),
+    )
+
+
+# -- resolving the input into a structural view ------------------------------
+
+
+def _resolve(
+    graph_like: Any,
+) -> tuple[dict[str, Any], list[Any], dict[str, dict[str, Any]] | None, str | None]:
+    branches: dict[str, dict[str, Any]] | None = None
+    if hasattr(graph_like, "branches"):
+        branches = graph_like.branches
+    elif hasattr(graph_like, "builder") and hasattr(graph_like.builder, "branches"):
+        branches = graph_like.builder.branches
+
+    structural = graph_like
+    if not hasattr(structural, "get_graph"):
+        if hasattr(structural, "compile"):
+            try:
+                structural = structural.compile()
+            except Exception as exc:  # surfaced as a finding, not raised
+                return {}, [], branches, str(exc)
+        if not hasattr(structural, "get_graph"):
+            if hasattr(structural, "nodes") and hasattr(structural, "edges"):
+                return dict(structural.nodes), list(structural.edges), branches, None
+            raise TypeError(
+                f"{type(graph_like).__name__} does not look like a graph: expected "
+                f"`.get_graph()`, `.compile()`, or `.nodes`/`.edges`"
+            )
+
+    graph = structural.get_graph()
+    return dict(graph.nodes), list(graph.edges), branches, None
+
+
+# -- Send() detection, to avoid false-positives on map-reduce fan-out -------
+
+
+def _send_targets(nodes: dict[str, Any], branches: dict[str, dict[str, Any]] | None) -> set[str]:
+    """Node names referenced as ``Send("name", ...)`` anywhere reachable.
+
+    ``Send`` lets a node or router dynamically fan out to a target with no
+    static edge at all, which is indistinguishable from a typo'd dead node
+    by structure alone. Scanning source for the literal target name is a
+    heuristic -- it misses dynamically computed names -- but it silences the
+    overwhelmingly common case of map-reduce fan-out.
+    """
+    targets: set[str] = set()
+    functions: list[Any] = []
+    for node in nodes.values():
+        func = getattr(node, "data", None)
+        if func is not None:
+            functions.append(func)
+    if branches:
+        for branch_map in branches.values():
+            for branch in branch_map.values():
+                path = getattr(branch, "path", None)
+                functions.append(getattr(path, "func", path))
+
+    for func in functions:
+        real = getattr(func, "func", func)  # unwrap RunnableCallable-style wrappers
+        try:
+            source = textwrap.dedent(inspect.getsource(real))
+            tree = ast.parse(source)
+        except (OSError, TypeError, SyntaxError):
+            continue
+        for call in ast.walk(tree):
+            if not isinstance(call, ast.Call):
+                continue
+            name = call.func.id if isinstance(call.func, ast.Name) else None
+            if name != "Send" or not call.args:
+                continue
+            first = call.args[0]
+            if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                targets.add(first.value)
+    return targets
+
+
+# -- reachability -------------------------------------------------------------
+
+
+def _bfs(start: str, adjacency: dict[str, set[str]]) -> set[str]:
+    seen = {start}
+    queue = deque([start])
+    while queue:
+        current = queue.popleft()
+        for neighbor in adjacency.get(current, ()):
+            if neighbor not in seen:
+                seen.add(neighbor)
+                queue.append(neighbor)
+    return seen
+
+
+# -- individual rules ----------------------------------------------------------
+
+
+def _unreachable_finding(name: str, send_targets: set[str]) -> Finding:
+    if name in send_targets:
+        return Finding(
+            rule="LG001",
+            node=name,
+            message=(
+                f"{name!r} has no static edge, but is referenced by a `Send(...)` "
+                f"call -- likely a map-reduce fan-out target, not dead code"
+            ),
+            severity=Severity.LOW,
+            caveat="Confirm the Send() target string is not a leftover from a rename.",
+        )
+    return Finding(
+        rule="LG001",
+        node=name,
+        message=f"{name!r} has no incoming edge and no path from START; it can never run",
+        severity=Severity.HIGH,
+        caveat=(
+            "If this node is only reached via `Send(...)` with a dynamically "
+            "computed name, this heuristic cannot see that -- verify manually."
+        ),
+    )
+
+
+def _check_conditional_branches(
+    branches: dict[str, dict[str, Any]], nodes: dict[str, Any]
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for source, branch_map in branches.items():
+        for branch in branch_map.values():
+            ends: dict[str, str] = dict(getattr(branch, "ends", {}) or {})
+            if not ends:
+                continue
+            path = getattr(branch, "path", None)
+            func = getattr(path, "func", path)
+            declared = _declared_return_literals(func)
+            if declared is None:
+                continue
+            confidence, literals = declared
+            missing = literals - set(ends)
+            for value in sorted(missing):
+                findings.append(
+                    Finding(
+                        rule="LG003",
+                        node=source,
+                        message=(
+                            f"router can return {value!r}, which has no matching "
+                            f"entry in the path_map ({sorted(ends)}) -- this raises "
+                            f"KeyError at runtime the first time this branch is taken"
+                        ),
+                        severity=Severity.HIGH if confidence == "type" else Severity.MEDIUM,
+                        caveat=(
+                            ""
+                            if confidence == "type"
+                            else "Detected via best-effort source scan, not a type "
+                            "annotation -- verify the router can truly return this."
+                        ),
+                    )
+                )
+            # The reverse direction: a path_map entry the router's own
+            # declared type can never produce is dead routing code, not a
+            # crash risk. Only trusted when confidence is "type", since the
+            # AST heuristic can under-count literals and would false-positive.
+            if confidence == "type":
+                unreachable = set(ends) - literals
+                for key in sorted(unreachable):
+                    findings.append(
+                        Finding(
+                            rule="LG005",
+                            node=source,
+                            message=(
+                                f"path_map branch {key!r} -> {ends[key]!r} is declared "
+                                f"but the router's return type never produces {key!r}"
+                            ),
+                            severity=Severity.LOW,
+                            caveat=(
+                                "Dead routing code, not a crash risk -- "
+                                "safe to leave if intentional."
+                            ),
+                        )
+                    )
+    return findings
+
+
+def _declared_return_literals(func: Any) -> tuple[str, set[str]] | None:
+    """Return (confidence, literal-values) the router's return type allows.
+
+    ``"type"`` confidence comes from an explicit ``Literal[...]`` return
+    annotation and is close to certain. ``"ast"`` confidence comes from
+    scanning ``return "..."`` statements in the source and is a heuristic
+    lower bound -- it can both miss dynamic returns and, in principle, list
+    a value some other branch makes unreachable.
+    """
+    try:
+        hints = typing.get_type_hints(func)
+    except Exception:  # forward refs, missing imports, etc.
+        hints = {}
+    ret = hints.get("return")
+    args = getattr(ret, "__args__", None)
+    if args and all(isinstance(a, str) for a in args):
+        return "type", set(args)
+
+    try:
+        source = textwrap.dedent(inspect.getsource(func))
+        tree = ast.parse(source)
+    except (OSError, TypeError, SyntaxError):
+        return None
+
+    literals: set[str] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Return) or node.value is None:
+            continue
+        literals.update(_string_constants(node.value))
+    return ("ast", literals) if literals else None
+
+
+def _string_constants(expr: ast.expr) -> set[str]:
+    """Best-effort: collect string literals an expression could evaluate to.
+
+    Handles the common ``a if cond else b`` and ``a or b`` shapes directly;
+    anything else (f-strings, variables, function calls) is simply not
+    counted, which only makes this heuristic under-report, never over-report.
+    """
+    if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
+        return {expr.value}
+    if isinstance(expr, ast.IfExp):
+        return _string_constants(expr.body) | _string_constants(expr.orelse)
+    if isinstance(expr, ast.BoolOp):
+        found: set[str] = set()
+        for value in expr.values:
+            found |= _string_constants(value)
+        return found
+    return set()

langgraph_lint/integrations.py

@@ -0,0 +1,125 @@
+"""Expose langgraph-lint as a tool for LangChain/LangGraph agents.
+
+Requires the ``agent`` extra::
+
+    pip install "langgraph-lint[agent]"
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+try:
+    from langchain_core.tools import tool
+except ImportError as exc:
+    raise ImportError(
+        "langgraph-lint's agent integration needs langchain-core. "
+        'Install it with: pip install "langgraph-lint[agent]"'
+    ) from exc
+
+from langgraph_lint.cli import _load_target
+from langgraph_lint.core import lint
+from langgraph_lint.models import Severity
+
+MAX_RESULTS = 50
+
+
+@tool
+def check_langgraph_graph(target: str, min_severity: str = "medium") -> str:
+    """Check a LangGraph graph for wiring bugs it won't catch itself.
+
+    Finds nodes with no path from START (dead code) and conditional router
+    functions whose declared return type includes a value missing from their
+    path_map -- that one is a KeyError waiting to happen on whichever input
+    first takes that branch.
+
+    Args:
+        target: The graph to check, as "module.path:attribute", e.g.
+            "myapp.graph:app". The module must be importable from the
+            current working directory.
+        min_severity: One of "high", "medium", "low". Defaults to "medium".
+
+    Returns:
+        JSON with the finding count and details. Every finding carries a
+        "caveat" -- read it before reporting anything as a confirmed bug;
+        dynamic patterns like Send()-based fan-out can look identical to a
+        mistake from static structure alone.
+    """
+    try:
+        graph_like = _load_target(target)
+    except (ValueError, ImportError, AttributeError) as exc:
+        return json.dumps({"error": str(exc)})
+
+    try:
+        severity = Severity(min_severity.lower())
+    except ValueError:
+        return json.dumps(
+            {"error": f"min_severity must be high, medium or low; got {min_severity!r}"}
+        )
+
+    try:
+        findings = lint(graph_like)
+    except TypeError as exc:
+        return json.dumps({"error": str(exc)})
+
+    order = {Severity.HIGH: 0, Severity.MEDIUM: 1, Severity.LOW: 2}
+    threshold = order[severity]
+    findings = [f for f in findings if order[f.severity] <= threshold]
+    capped = findings[:MAX_RESULTS]
+
+    return json.dumps(
+        {
+            "total_findings": len(findings),
+            "returned": len(capped),
+            "truncated": len(capped) < len(findings),
+            "findings": [f.as_dict() for f in capped],
+        },
+        indent=2,
+    )
+
+
+def get_tools() -> list[Any]:
+    """Return the langgraph-lint tool for binding to an agent."""
+    return [check_langgraph_graph]
+
+
+SYSTEM_PROMPT = """You audit LangGraph graphs for wiring defects.
+
+Rules:
+1. Every finding has a "caveat". Read it -- Send()-based fan-out and
+   human-in-the-loop interrupts are legitimate patterns that can resemble
+   a defect from structure alone.
+2. A HIGH severity dangling-conditional-branch finding (LG003, "type"
+   confidence) is close to certain: it comes from the router's own type
+   annotation, not a guess.
+3. Explain *why* each finding matters in terms of what would go wrong at
+   runtime, not just that a rule fired.
+"""
+
+
+def build_graph(model: Any, system_prompt: str | None = None) -> Any:
+    """Build a prebuilt agent wired to the langgraph-lint tool.
+
+    Prefers ``langchain.agents.create_agent`` and falls back to the older
+    ``langgraph.prebuilt.create_react_agent`` if only ``langgraph`` (not
+    ``langchain``) is installed.
+    """
+    prompt = system_prompt or SYSTEM_PROMPT
+    try:
+        from langchain.agents import create_agent
+    except ImportError:
+        pass
+    else:
+        return create_agent(model, get_tools(), system_prompt=prompt)
+
+    try:
+        from langgraph.prebuilt import create_react_agent
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            'build_graph needs langgraph. Install: pip install "langgraph-lint[agent]"'
+        ) from exc
+    return create_react_agent(model, get_tools(), prompt=prompt)
+
+
+__all__ = ["SYSTEM_PROMPT", "build_graph", "check_langgraph_graph", "get_tools"]

langgraph_lint/models.py

@@ -0,0 +1,46 @@
+"""Core data types.
+
+Deliberately dependency-free: nothing here imports langgraph or langchain_core,
+so importing this module never requires either to be installed.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import Any
+
+
+class Severity(enum.StrEnum):
+    """Confidence that a finding is a genuine wiring defect.
+
+    ``HIGH``   -- provable from a type annotation or exact structural match.
+    ``MEDIUM`` -- true under the analyzer's stated assumptions, which a
+                  dynamic pattern (like ``Send``) could legitimately violate.
+    ``LOW``    -- informational; rarely worth a maintainer's time alone.
+    """
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Finding:
+    """A single suspected wiring defect in a graph."""
+
+    rule: str
+    node: str
+    message: str
+    severity: Severity = Severity.MEDIUM
+    #: Why this might be intentional. Every rule here has a legitimate
+    #: counter-pattern (Send-based fan-out, human-in-the-loop interrupts,
+    #: dynamically computed router outputs) and pretending otherwise makes
+    #: the tool an alert-fatigue machine, not a useful one.
+    caveat: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+    def __str__(self) -> str:
+        return f"[{self.severity.upper()}] {self.rule} ({self.node}): {self.message}"

langgraph_lint-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: langgraph-lint
+Version: 0.1.0
+Summary: Find LangGraph wiring bugs before they become a runtime KeyError.
+Project-URL: Homepage, https://github.com/mathewOracle/langgraph-lint
+Project-URL: Repository, https://github.com/mathewOracle/langgraph-lint
+Project-URL: Issues, https://github.com/mathewOracle/langgraph-lint/issues
+Author: mathewOracle
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,code-quality,graph,langchain,langgraph,linter,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: agent
+Requires-Dist: langchain-core>=0.3; extra == 'agent'
+Requires-Dist: langchain>=1.0; extra == 'agent'
+Requires-Dist: langgraph>=0.2; extra == 'agent'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: langgraph>=0.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langgraph-lint
+
+**Find LangGraph wiring bugs before they become a runtime `KeyError`.**
+
+LangGraph validates some things at `compile()` time — an edge to a node that doesn't exist, for instance, fails immediately and loudly. But a lot of real wiring bugs compile perfectly fine and only surface the first time a specific input takes a specific untested branch, weeks later, in production.
+
+```console
+$ langgraph-lint myapp.graph:app
+
+  [HIGH] LG003 (route_after_search): router can return 'maybe', which has no
+  matching entry in the path_map (['no', 'yes']) -- this raises KeyError at
+  runtime the first time this branch is taken
+
+  [HIGH] LG001 (validate_output): 'validate_output' has no incoming edge and
+  no path from START; it can never run
+
+2 finding(s) in myapp.graph:app.
+```
+
+That first finding is real, reproducible, and proven — not a guess:
+
+```python
+def router(state) -> Literal["yes", "no", "maybe"]:
+    ...
+
+graph.add_conditional_edges("a", router, {"yes": "b", "no": "c"})  # no "maybe"!
+
+compiled = graph.compile()      # succeeds. no warning. nothing.
+compiled.invoke({"x": 2})       # fine
+compiled.invoke({"x": 3})       # fine
+compiled.invoke({"x": 101})     # KeyError: 'maybe'  <- only now
+```
+
+`langgraph-lint` catches this the moment you write it, by checking the router's own `Literal[...]` return type against the `path_map` you gave `add_conditional_edges`. No invocation needed.
+
+## Install
+
+```console
+pip install langgraph-lint                # zero dependencies
+pip install "langgraph-lint[agent]"       # + a LangChain/LangGraph agent tool
+```
+
+## Use it as a CLI
+
+```console
+langgraph-lint myapp.graph:app             # module.path:attribute, like uvicorn
+langgraph-lint myapp.graph:app --min-severity high
+langgraph-lint myapp.graph:app --format json
+langgraph-lint myapp.graph:app --format github   # Actions annotations
+```
+
+`target` accepts a compiled graph, an uncompiled `StateGraph` builder, or any object with `.get_graph()` — so it also works on plain LangChain LCEL runnables, just with a smaller rule set (the conditional-branch check is LangGraph-specific). Exit code `1` on findings, `0` clean, `2` on error.
+
+## Use it as a library
+
+```python
+from langgraph_lint import lint
+
+for finding in lint(app):
+    print(finding)
+```
+
+## Use it in an agent
+
+```python
+from langgraph_lint.integrations import build_graph
+
+auditor = build_graph("anthropic:claude-sonnet-4-5")
+auditor.invoke({
+    "messages": [{"role": "user", "content": "Check myapp.graph:app for wiring bugs."}]
+})
+```
+
+Or `get_tools()` to bind `check_langgraph_graph` to your own agent.
+
+## Rules
+
+| Code | Catches | LangGraph catches it today? |
+|---|---|---|
+| `LG000` | Graph fails to `compile()` at all | Raises, but as a stack trace, not a lint finding |
+| `LG001` | A node with no path from `START` (dead code) | No |
+| `LG003` | A router's `Literal[...]` return type has a value missing from its `path_map` | **No — silent until that branch runs** |
+| `LG005` | A `path_map` branch the router's own return type can never produce (dead routing code, the mirror image of LG003) | No |
+
+Two rules that seemed obviously useful up front — "node with no path to `END`" and "duplicate edge" — got cut before release. Both turned out to be structurally undetectable: LangGraph auto-inserts an implicit escape-hatch edge to `END` on essentially every node (even inside a genuine, unbreakable cycle — verified), and plain edges are deduplicated into a `set` before `get_graph()` ever sees them. A rule that can never fire is worse than no rule; better to ship four honest ones than six decorative ones.
+
+## On false positives
+
+Every rule here has a real counter-pattern, and this tool knows about the big one: **`Send()`-based map-reduce fan-out creates zero static edges** to its target node. A node reached only via `Send("worker", ...)` has no incoming edge in the graph's structure at all — indistinguishable, by structure alone, from a typo'd dead node. `langgraph-lint` scans node and router source for `Send("literal_name", ...)` calls and downgrades those findings to informational rather than screaming at correct, idiomatic code.
+
+Similarly:
+- `LG005`'s check on unreachable `path_map` branches only trusts a `Literal[...]` type annotation, never the AST heuristic, since a false claim of "this can never happen" is worse than staying silent.
+- `LG003`'s AST-based fallback (used when a router has no `Literal[...]` annotation) is a heuristic, not a guarantee — it scans `return "..."` statements and can miss dynamically computed values. Those findings are `MEDIUM`, not `HIGH`, and say so explicitly.
+
+Every `Finding` carries a `caveat` field for exactly this reason. `LG003` findings backed by an actual type annotation carry an empty caveat, because there's nothing to hedge — that's about as close to certain as static analysis gets.
+
+## Compatibility
+
+Built and tested against `langgraph==1.2.11`. The `LG003`/`LG005` branch checks read `StateGraph.branches` and `BranchSpec.path`/`.ends` -- internal, non-public attributes, not a documented API. They've been stable across recent LangGraph releases, but a future LangGraph refactor could rename them; if that happens, `langgraph-lint` degrades to `LG001`-only (dead-node detection, which only needs the public `get_graph()`), not a crash -- worth knowing if you pin an unusually old or new LangGraph version.
+
+## Development
+
+```console
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check . && mypy src
+```
+
+The test suite builds real `langgraph.StateGraph` objects rather than mocks. The flagship test doesn't just assert a finding fires — it then actually invokes the compiled graph and confirms the predicted `KeyError` really happens, so the rule's claim is proven, not just plausible.
+
+## License
+
+MIT

langgraph_lint-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+langgraph_lint/__init__.py,sha256=hSxQk-vNtWFk7oOz21cKXvSB1SdAHY8MdksQYgPKBKM,298
+langgraph_lint/cli.py,sha256=OjPPVVeCWTEeXibRUUk5dCnhox26PMds7BVJFuRiwfE,3440
+langgraph_lint/core.py,sha256=CT0T_rq1_-Gw-W0GIT70k1vaDZ4BlPofT3Mphes-R6o,11633
+langgraph_lint/integrations.py,sha256=R9aXBEgm2DOwIUeMOGjj4RjAh4m0lhLnqVbc908nea4,4147
+langgraph_lint/models.py,sha256=qd00S_ubYzRmInpaewzi-4uRHX0objjtzvYiEk-1-jQ,1426
+langgraph_lint-0.1.0.dist-info/METADATA,sha256=3Hn73AwPiz81bI4GBfuzSh5cLxwc98Fquymal1FxBTE,7262
+langgraph_lint-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+langgraph_lint-0.1.0.dist-info/entry_points.txt,sha256=w7emlh2zGmJ_d2dLrO2H_GoelFi2j_8Sps4rzsTj20s,59
+langgraph_lint-0.1.0.dist-info/licenses/LICENSE,sha256=3TnGsRZT9l6u_Gy8bLyT7rkaHjxEPkLAcPQw-lJj214,1069
+langgraph_lint-0.1.0.dist-info/RECORD,,

langgraph_lint-0.1.0.dist-info/WHEEL

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

langgraph_lint-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+langgraph-lint = langgraph_lint.cli:main

langgraph_lint-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mathewOracle
+
+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.