plain-parser 0.1.2.dev5__tar.gz → 0.1.2.dev6__tar.gz

{plain_parser-0.1.2.dev5 → plain_parser-0.1.2.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plain-parser
-Version: 0.1.2.dev5
+Version: 0.1.2.dev6
 Summary: Parser for ***plain specification files
 License-Expression: MIT
 License-File: LICENSE
@@ -10,7 +10,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Compilers
 Requires-Python: >=3.11
 Requires-Dist: mistletoe<2,>=1.6.0
-Requires-Dist: networkx<4,>=3.6.1
 Requires-Dist: python-frontmatter<2,>=1.3.0
 Requires-Dist: python-liquid2<0.5,>=0.4.0
 Requires-Dist: pyyaml<7,>=6

{plain_parser-0.1.2.dev5 → plain_parser-0.1.2.dev6}/pyproject.toml

@@ -20,7 +20,6 @@ dependencies = [
     "python-liquid2>=0.4.0,<0.5",
     "mistletoe>=1.6.0,<2",
     "python-frontmatter>=1.3.0,<2",
-    "networkx>=3.6.1,<4",
     "pyyaml>=6,<7",
 ]
 

{plain_parser-0.1.2.dev5 → plain_parser-0.1.2.dev6}/src/plain_parser/concept_utils.py

@@ -1,11 +1,11 @@
 import re
 from copy import deepcopy
+from graphlib import CycleError, TopologicalSorter
 from typing import Optional
 
 import mistletoe.block_token
-import networkx as nx
 
-from plain_parser import plain_spec
+from plain_parser import graph, plain_spec
 from plain_parser.exceptions import PlainSyntaxError
 
 # These are reserved concept names that are pre-defined and must not be redefined in the definitions section.
@@ -186,34 +186,63 @@ def build_adjacency_list(definitions: Optional[list[dict]]) -> tuple[dict, dict]
     return adjacency_list, concept_definitions
 
 
+MAX_REPORTED_CYCLES = 10
+
+
+def format_cycles_error(adjacency_list: dict[str, list[str]], concept_definitions: dict[str, dict]) -> str:
+    """
+    List the elementary cycles in the graph, each as a "Cycle N: :A: -> :B: -> :A:" line
+    followed by the definition of every concept in the cycle. Arrows point from a definition
+    to a concept it mentions, each cycle starts at its earliest-defined concept, and cycles
+    are ordered by definition position, so the report reads top to bottom like the file.
+    At most MAX_REPORTED_CYCLES are listed; the search stops once one more than that is found.
+    """
+    position = {concept: index for index, concept in enumerate(concept_definitions)}
+    cycles = []
+    # key the graph in definition order so a search cut short by the limit has found the earliest cycles
+    by_position = {concept: adjacency_list[concept] for concept in [*concept_definitions, *adjacency_list]}
+    for cycle in graph.simple_cycles(by_position, limit=MAX_REPORTED_CYCLES + 1):
+        # reverse since simple_cycles edges point from a used concept to the one defined with it
+        cycle = cycle[::-1]
+        first = min(range(len(cycle)), key=lambda i: position[cycle[i]])
+        cycles.append(cycle[first:] + cycle[:first])
+    cycles.sort(key=lambda cycle: (position[cycle[0]], len(cycle), [position[c] for c in cycle]))
+
+    if len(cycles) > MAX_REPORTED_CYCLES:
+        cycles = cycles[:MAX_REPORTED_CYCLES]
+        lines = [
+            f"Plain syntax error: Found more than {MAX_REPORTED_CYCLES} cycles in concept definitions. Cycles are not allowed.",
+            f"Showing the first {MAX_REPORTED_CYCLES}.",
+        ]
+    else:
+        lines = [f"Plain syntax error: Found {len(cycles)} cycle(s) in concept definitions. Cycles are not allowed."]
+    for number, cycle in enumerate(cycles, start=1):
+        lines.append("")
+        lines.append(f"Cycle {number}: " + " -> ".join(cycle + [cycle[0]]))
+        # concepts defined on one line can share a cycle; print that line once
+        lines.extend(dict.fromkeys(concept_definitions[concept]["markdown"] for concept in cycle))
+    return "\n".join(lines)
+
+
 def sort_definitions(definitions: list[dict]) -> list[dict]:
     if len(definitions) <= 1:
         return
 
     adjacency_list, concept_definitions = build_adjacency_list(definitions)
 
-    concept_graph = nx.DiGraph()
+    # adjacency_list maps a used concept to the concepts defined in terms of it,
+    # so the used concept is a predecessor of each of them
+    sorter: TopologicalSorter[str] = TopologicalSorter()
     for node, neighbors in adjacency_list.items():
+        sorter.add(node)
         for neighbour in neighbors:
-            concept_graph.add_edge(node, neighbour)
-        if not neighbors:
-            concept_graph.add_node(node)
-
-    if not nx.is_directed_acyclic_graph(concept_graph):
-        msg = "Found cycles in the concept graph. Cycles are not allowed. "
-        all_cycles = list(nx.simple_cycles(concept_graph))
-
-        for cycle in all_cycles:
-            cyclic_definitions = []
-            cyclic_definitions.append(concept_definitions[cycle[0]]["markdown"])
-            cyclic_definitions.append(concept_definitions[cycle[1]]["markdown"])
-            msg += "Cyclic definitions:\n"
-            msg += "\n".join(cyclic_definitions)
-            msg += "\n"
+            sorter.add(neighbour, node)
 
-        raise PlainSyntaxError(f"Plain syntax error: {msg}")
+    try:
+        order = list(sorter.static_order())
+    except CycleError:
+        raise PlainSyntaxError(format_cycles_error(adjacency_list, concept_definitions)) from None
 
-    order = list(nx.topological_sort(concept_graph))
     if len(order) > 0:
         definition_to_order_idx = {
             plain_spec.hash_text(str(concept_definitions[concept])): idx for idx, concept in enumerate(order)

plain_parser-0.1.2.dev6/src/plain_parser/graph.py

@@ -0,0 +1,164 @@
+"""Cycle search over a directed graph given as a mapping from node to its successors.
+
+Nodes that appear only as successors are treated as having no outgoing edges.
+
+The search is Johnson's algorithm, written from the pseudocode in the paper, with the
+strongly connected components found by Tarjan's algorithm as given on Wikipedia.
+
+- D. B. Johnson, "Finding all the elementary circuits of a directed graph",
+  SIAM J. Comput. 4(1):77-84, 1975, doi:10.1137/0204007
+- R. Tarjan, "Depth-first search and linear graph algorithms",
+  SIAM J. Comput. 1(2):146-160, 1972, doi:10.1137/0201010
+- https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm
+
+Both searches keep their own stack of frames instead of recursing, so the depth of a
+tangle is not limited by Python's recursion limit.
+"""
+
+import heapq
+from collections import defaultdict
+from collections.abc import Hashable, Iterable, Iterator, Mapping
+from typing import Optional, TypeVar
+
+Node = TypeVar("Node", bound=Hashable)
+
+
+def _successors(graph: Mapping[Node, Iterable[Node]]) -> dict[Node, list[Node]]:
+    # a repeated edge would otherwise yield every cycle through it once per repeat
+    successors = {node: list(dict.fromkeys(targets)) for node, targets in graph.items()}
+    for targets in list(successors.values()):
+        for target in targets:
+            successors.setdefault(target, [])
+    return successors
+
+
+def strongly_connected_components(graph: Mapping[Node, Iterable[Node]]) -> list[set[Node]]:
+    """Tarjan: one depth-first walk, each node stamped with its visit index and the lowest
+    index it can reach; a node whose lowest reachable index is its own closes a component."""
+    successors = _successors(graph)
+    index: dict[Node, int] = {}
+    lowlink: dict[Node, int] = {}
+    stack: list[Node] = []
+    on_stack: set[Node] = set()
+    components: list[set[Node]] = []
+
+    def visit(node: Node) -> tuple[Node, Iterator[Node]]:
+        index[node] = lowlink[node] = len(index)
+        stack.append(node)
+        on_stack.add(node)
+        return node, iter(successors[node])
+
+    for root in successors:
+        if root in index:
+            continue
+        frames = [visit(root)]
+        while frames:
+            node, targets = frames[-1]
+            for target in targets:
+                if target not in index:
+                    frames.append(visit(target))
+                    break
+                if target in on_stack:
+                    lowlink[node] = min(lowlink[node], index[target])
+            else:
+                frames.pop()
+                if frames:
+                    parent = frames[-1][0]
+                    lowlink[parent] = min(lowlink[parent], lowlink[node])
+                if lowlink[node] == index[node]:
+                    component: set[Node] = set()
+                    while True:
+                        member = stack.pop()
+                        on_stack.discard(member)
+                        component.add(member)
+                        if member == node:
+                            break
+                    components.append(component)
+    return components
+
+
+def _cycles_through(adjacency: dict[Node, list[Node]], s: Node) -> Iterator[list[Node]]:
+    """Johnson's CIRCUIT: every elementary cycle through `s` in one strongly connected component.
+
+    A node is blocked while it is on the path, and stays blocked after backtracking until a
+    cycle is found through some node it was waiting on."""
+    blocked: set[Node] = set()
+    blocked_map: dict[Node, set[Node]] = defaultdict(set)
+
+    def unblock(node: Node) -> None:
+        pending = [node]
+        while pending:
+            current = pending.pop()
+            blocked.discard(current)
+            pending.extend(waiting for waiting in blocked_map.pop(current, ()) if waiting in blocked)
+
+    path = [s]
+    blocked.add(s)
+    frames = [iter(adjacency[s])]
+    found_below = [False]
+    while frames:
+        node = path[-1]
+        for target in frames[-1]:
+            if target == s:
+                yield list(path)
+                found_below[-1] = True
+            elif target not in blocked:
+                path.append(target)
+                blocked.add(target)
+                frames.append(iter(adjacency[target]))
+                found_below.append(False)
+                break
+        else:
+            frames.pop()
+            path.pop()
+            if found_below.pop():
+                unblock(node)
+                if found_below:
+                    found_below[-1] = True
+            else:
+                for target in adjacency[node]:
+                    blocked_map[target].add(node)
+
+
+def _all_cycles(graph: Mapping[Node, Iterable[Node]]) -> Iterator[list[Node]]:
+    """Johnson's main loop: every cycle lies inside one strongly connected component, and
+    every cycle inside a component either passes through its least node or survives that
+    node's removal. So search each component from its least node, drop the node, and split
+    what is left into components again. Components are taken least node first, so a caller
+    that stops early has seen the cycles through the earliest nodes."""
+    successors = _successors(graph)
+    for node, targets in successors.items():
+        if node in targets:
+            yield [node]
+    successors = {node: [t for t in targets if t != node] for node, targets in successors.items()}
+    position = {node: i for i, node in enumerate(successors)}
+
+    # components are disjoint, so no two entries share a least position and the sets are never compared
+    components: list[tuple[int, set[Node]]] = []
+
+    def push_components(adjacency: Mapping[Node, Iterable[Node]]) -> None:
+        for component in strongly_connected_components(adjacency):
+            if len(component) >= 2:
+                heapq.heappush(components, (min(map(position.__getitem__, component)), component))
+
+    push_components(successors)
+    while components:
+        _, component = heapq.heappop(components)
+        s = min(component, key=position.__getitem__)
+        adjacency = {n: [t for t in successors[n] if t in component] for n in component}
+        yield from _cycles_through(adjacency, s)
+        del adjacency[s]
+        for targets in adjacency.values():
+            if s in targets:
+                targets.remove(s)
+        push_components(adjacency)
+
+
+def simple_cycles(graph: Mapping[Node, Iterable[Node]], limit: Optional[int] = None) -> Iterator[list[Node]]:
+    """Yield the elementary cycles of `graph`, each as its nodes in edge order, stopping
+    after `limit` cycles when one is given. Self-loops come first; longer cycles follow in
+    order of their earliest node in `graph`'s iteration order."""
+    for found, cycle in enumerate(_all_cycles(graph), start=1):
+        if limit is not None and found > limit:
+            return
+        yield cycle

plain_parser-0.1.2.dev6/tests/data/plainfileparser/cyclic_definitions_across_import.plain

@@ -0,0 +1,13 @@
+---
+import:
+    - required_concepts
+---
+
+***definitions***
+- :Concept: is the concept that :DependantConcept: builds on.
+
+***implementation reqs***
+- The :Concept: concept must be implemented.
+
+***functional specs***
+- Implement the :Concept: concept.

plain_parser-0.1.2.dev6/tests/data/plainfileparser/cyclic_definitions_long.plain

@@ -0,0 +1,11 @@
+***definitions***
+- :A: uses :B:.
+- :B: uses :C:.
+- :C: uses :A:.
+- :D: is on its own.
+
+***implementation reqs***
+- The :D: concept must be implemented.
+
+***functional specs***
+- Implement the :D: concept.

plain_parser-0.1.2.dev6/tests/data/plainfileparser/cyclic_definitions_sub_bullet.plain

@@ -0,0 +1,11 @@
+***definitions***
+- :Order: is a purchase.
+  - It is placed by a :Customer:.
+- :Customer: is a buyer with :Order: items.
+- :Receipt: records an :Order:.
+
+***implementation reqs***
+- The :Receipt: concept must be implemented.
+
+***functional specs***
+- Implement the :Receipt: concept.

plain_parser-0.1.2.dev6/tests/test_concept_utils.py

@@ -0,0 +1,179 @@
+import re
+
+import pytest
+
+from plain_parser import concept_utils
+from plain_parser.exceptions import PlainSyntaxError
+
+
+def definitions(*markdown: str) -> list[dict]:
+    return [{"markdown": line} for line in markdown]
+
+
+def defined_concepts(sorted_definitions: list[dict]) -> list[str]:
+    return [concept_utils.extract_concepts_from_definition(d["markdown"])[0][0] for d in sorted_definitions]
+
+
+def test_sort_single_definition_is_unchanged():
+    defs = definitions("- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:"]
+
+
+def test_sort_definitions_without_concept_references_keeps_file_order():
+    defs = definitions("- :B: is y.", "- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":B:", ":A:"]
+
+
+def test_sort_places_dependency_before_dependant():
+    defs = definitions("- :B: uses :A:.", "- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:", ":B:"]
+
+
+def test_sort_resolves_diamond_dependencies():
+    defs = definitions("- :D: uses :B: and :C:.", "- :B: uses :A:.", "- :C: uses :A:.", "- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    order = defined_concepts(defs)
+    assert order.index(":A:") < order.index(":B:") < order.index(":D:")
+    assert order.index(":A:") < order.index(":C:") < order.index(":D:")
+
+
+def test_sort_follows_references_in_sub_bullets():
+    defs = definitions("- :B: is y.\n  - it uses :A:.", "- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:", ":B:"]
+
+
+def test_sort_places_multi_concept_definition_before_its_dependants():
+    defs = definitions("- :C: uses :A: and :B:.", "- :A:, :B: are twins.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:", ":C:"]
+
+
+def test_sort_ignores_self_reference():
+    defs = definitions("- :B: uses :A:.", "- :A: is like :A:.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:", ":B:"]
+
+
+def test_sort_ignores_predefined_concepts():
+    defs = definitions("- :B: uses :A: and :Implementation:.", "- :A: is x.")
+    concept_utils.sort_definitions(defs)
+    assert defined_concepts(defs) == [":A:", ":B:"]
+
+
+def test_sort_rejects_two_node_cycle_and_lists_both_definitions():
+    defs = definitions("- :A: uses :B:.", "- :B: uses :A:.")
+    with pytest.raises(PlainSyntaxError, match="Cycles are not allowed") as exc_info:
+        concept_utils.sort_definitions(defs)
+    assert "- :A: uses :B:." in str(exc_info.value)
+    assert "- :B: uses :A:." in str(exc_info.value)
+
+
+def test_sort_rejects_long_cycle_and_lists_every_definition_on_it():
+    defs = definitions("- :A: uses :B:.", "- :B: uses :C:.", "- :C: uses :A:.", "- :D: is on its own.")
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(defs)
+    message = str(exc_info.value)
+    for definition in ("- :A: uses :B:.", "- :B: uses :C:.", "- :C: uses :A:."):
+        assert definition in message
+    assert "- :D: is on its own." not in message
+
+
+def test_sort_rejects_cycle_through_multi_concept_definition():
+    defs = definitions("- :A:, :B: use :C:.", "- :C: uses :B:.")
+    with pytest.raises(PlainSyntaxError, match="Cycles are not allowed"):
+        concept_utils.sort_definitions(defs)
+
+
+def test_sort_rejects_graph_with_two_separate_cycles_and_reports_both():
+    defs = definitions("- :A: uses :B:.", "- :B: uses :A:.", "- :X: uses :Y:.", "- :Y: uses :X:.")
+    with pytest.raises(PlainSyntaxError, match="Found 2 cycle") as exc_info:
+        concept_utils.sort_definitions(defs)
+    message = str(exc_info.value)
+    assert "Cycle 1: :A: -> :B: -> :A:" in message
+    assert "Cycle 2: :X: -> :Y: -> :X:" in message
+
+
+def test_sort_reports_every_elementary_cycle_of_a_tangle():
+    defs = definitions(
+        "- :Order: is placed by a :Customer: and billed by an :Invoice:.",
+        "- :Customer: has :Order: items and :Invoice: items.",
+        "- :Invoice: bills an :Order: to a :Customer:.",
+    )
+    with pytest.raises(PlainSyntaxError, match="Found 5 cycle") as exc_info:
+        concept_utils.sort_definitions(defs)
+    assert str(exc_info.value).count("Cycle ") == 5
+
+
+def test_sort_caps_the_number_of_reported_cycles():
+    defs = definitions(
+        "- :Order: is placed by a :Customer:, billed by an :Invoice:, settled by a :Payment:.",
+        "- :Customer: has :Order:, :Invoice: and :Payment: items.",
+        "- :Invoice: bills an :Order: to a :Customer: and is settled by a :Payment:.",
+        "- :Payment: settles an :Invoice: for an :Order: by a :Customer:.",
+    )
+    with pytest.raises(PlainSyntaxError, match="Found more than 10 cycles") as exc_info:
+        concept_utils.sort_definitions(defs)
+    message = str(exc_info.value)
+    assert "Showing the first 10." in message
+    assert message.count("Cycle ") == 10
+
+
+def test_sort_reports_cycle_in_reference_order():
+    defs = definitions("- :A: uses :B:.", "- :B: uses :C:.", "- :C: uses :A:.")
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(defs)
+    assert "Cycle 1: :A: -> :B: -> :C: -> :A:\n- :A: uses :B:.\n- :B: uses :C:.\n- :C: uses :A:." in str(exc_info.value)
+
+
+def test_sort_rejects_cycle_that_also_references_undefined_concept():
+    defs = definitions("- :A: uses :B: and :Ghost:.", "- :B: uses :A:.")
+    with pytest.raises(PlainSyntaxError, match="Cycles are not allowed"):
+        concept_utils.sort_definitions(defs)
+
+
+def separate_two_cycles(count: int) -> list[str]:
+    return [line for i in range(count) for line in (f"- :A{i}: uses :B{i}:.", f"- :B{i}: uses :A{i}:.")]
+
+
+def cycle_lines(message: str) -> list[str]:
+    return [line for line in message.splitlines() if line.startswith("Cycle ")]
+
+
+def test_sort_reports_exactly_the_maximum_without_truncating():
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(definitions(*separate_two_cycles(10)))
+    message = str(exc_info.value)
+    assert "Found 10 cycle(s)" in message
+    assert "Showing" not in message
+    assert len(cycle_lines(message)) == 10
+
+
+def test_sort_truncated_report_shows_the_earliest_defined_cycles():
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(definitions(*separate_two_cycles(12)))
+    lines = cycle_lines(str(exc_info.value))
+    assert lines[0] == "Cycle 1: :A0: -> :B0: -> :A0:"
+    assert lines[-1] == "Cycle 10: :A9: -> :B9: -> :A9:"
+
+
+def test_sort_truncation_follows_definition_order_not_first_mention():
+    # :A10: and :A11: are mentioned on the first line but defined last, so their cycles are not among the first 10
+    defs = separate_two_cycles(12)
+    defs[0] = "- :A0: uses :B0:, :A10: and :A11:."
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(definitions(*defs))
+    lines = cycle_lines(str(exc_info.value))
+    assert lines[-1] == "Cycle 10: :A9: -> :B9: -> :A9:"
+    assert not [line for line in lines if re.search(r":A1[01]:", line)]
+
+
+def test_sort_prints_a_shared_definition_once_per_cycle():
+    defs = definitions("- :A:, :B: use :X: and :Y:.", "- :X: uses :B:.", "- :Y: uses :A:.")
+    with pytest.raises(PlainSyntaxError) as exc_info:
+        concept_utils.sort_definitions(defs)
+    blocks = str(exc_info.value).split("\n\n")[1:]
+    assert blocks and all(block.count("- :A:, :B: use :X: and :Y:.") == 1 for block in blocks)

plain_parser-0.1.2.dev6/tests/test_graph.py

@@ -0,0 +1,130 @@
+import random
+import sys
+from itertools import permutations
+
+import pytest
+
+from plain_parser import graph
+
+
+def canonical(cycles) -> set[tuple]:
+    """Rotate each cycle to start at its smallest node so equal cycles compare equal."""
+    result = set()
+    for cycle in cycles:
+        start = cycle.index(min(cycle))
+        result.add(tuple(cycle[start:] + cycle[:start]))
+    return result
+
+
+def brute_force_cycles(adjacency: dict[int, list[int]]) -> set[tuple]:
+    """Try every node subset in every order; keep the ones that close a loop."""
+    nodes = sorted(adjacency)
+    found = set()
+    for length in range(1, len(nodes) + 1):
+        for perm in permutations(nodes, length):
+            if all(perm[(i + 1) % length] in adjacency[perm[i]] for i in range(length)):
+                found.add(perm)
+    return canonical(list(c) for c in found)
+
+
+def test_dag_has_no_cycles():
+    assert list(graph.simple_cycles({"a": ["b"], "b": ["c"], "c": []})) == []
+
+
+def test_empty_graph():
+    assert list(graph.simple_cycles({})) == []
+
+
+def test_self_loop():
+    assert list(graph.simple_cycles({"a": ["a"]})) == [["a"]]
+
+
+def test_two_node_cycle():
+    assert canonical(graph.simple_cycles({"a": ["b"], "b": ["a"]})) == {("a", "b")}
+
+
+def test_targets_only_nodes_are_tolerated():
+    assert canonical(graph.simple_cycles({"a": ["b", "ghost"], "b": ["a"]})) == {("a", "b")}
+
+
+def test_complete_graph_on_three_nodes_has_five_cycles():
+    k3 = {n: [m for m in "abc" if m != n] for n in "abc"}
+    assert len(list(graph.simple_cycles(k3))) == 5
+
+
+def test_complete_graph_on_four_nodes_has_twenty_cycles():
+    k4 = {n: [m for m in "abcd" if m != n] for n in "abcd"}
+    assert len(list(graph.simple_cycles(k4))) == 20
+
+
+def test_two_separate_cycles_are_both_found():
+    g = {"a": ["b"], "b": ["a"], "x": ["y"], "y": ["x"], "lone": []}
+    assert canonical(graph.simple_cycles(g)) == {("a", "b"), ("x", "y")}
+
+
+def test_cycles_are_reported_in_edge_order():
+    g = {"a": ["b"], "b": ["c"], "c": ["a"]}
+    (cycle,) = list(graph.simple_cycles(g))
+    for node, following in zip(cycle, cycle[1:] + cycle[:1]):
+        assert following in g[node]
+
+
+def test_strongly_connected_components():
+    g = {"a": ["b"], "b": ["a", "c"], "c": ["d"], "d": ["c"], "e": []}
+    components = graph.strongly_connected_components(g)
+    assert sorted(sorted(c) for c in components) == [["a", "b"], ["c", "d"], ["e"]]
+
+
+def test_limit_stops_after_that_many_cycles():
+    k4 = {n: [m for m in "abcd" if m != n] for n in "abcd"}
+    assert len(list(graph.simple_cycles(k4, limit=10))) == 10
+    assert len(list(graph.simple_cycles(k4, limit=0))) == 0
+
+
+def test_acyclic_appendage_is_never_entered():
+    # a 2-cycle with a chain of 40 diamonds hanging off it: exponentially many paths, one cycle
+    g = {"a": ["b", "d0"], "b": ["a"]}
+    for i in range(40):
+        g[f"d{i}"] = [f"l{i}", f"r{i}"]
+        g[f"l{i}"] = g[f"r{i}"] = [f"d{i + 1}"]
+    g["d40"] = []
+    assert canonical(graph.simple_cycles(g)) == {("a", "b")}
+
+
+def test_repeated_edge_yields_each_cycle_once():
+    assert list(graph.simple_cycles({"a": ["b", "b"], "b": ["a", "a"]})) == [["a", "b"]]
+
+
+def test_limit_does_not_enumerate_the_rest():
+    # the complete graph on 14 nodes has billions of cycles; only a lazy search returns
+    k14 = {n: [m for m in range(14) if m != n] for n in range(14)}
+    assert len(list(graph.simple_cycles(k14, limit=11))) == 11
+
+
+def test_separate_cycles_come_in_graph_order():
+    g = {f"{name}{i}": [f"{name}{1 - i}"] for name in "pqrst" for i in range(2)}
+    assert [cycle[0][0] for cycle in graph.simple_cycles(g)] == list("pqrst")
+
+
+def test_cycle_longer_than_the_recursion_limit():
+    n = sys.getrecursionlimit() * 2
+    (cycle,) = list(graph.simple_cycles({i: [(i + 1) % n] for i in range(n)}))
+    assert len(cycle) == n
+
+
+def test_components_of_a_chain_longer_than_the_recursion_limit():
+    n = sys.getrecursionlimit() * 2
+    assert len(graph.strongly_connected_components({i: [i + 1] for i in range(n)})) == n + 1
+
+
+@pytest.mark.parametrize("seed", range(200))
+def test_matches_brute_force_on_random_graphs(seed):
+    rng = random.Random(seed)
+    n = rng.randint(1, 6)
+    density = rng.choice([0.2, 0.4, 0.7, 1.0])
+    adjacency = {u: [v for v in range(n) if rng.random() < density] for u in range(n)}
+    cycles = list(graph.simple_cycles(adjacency))
+    assert len(cycles) == len(canonical(cycles)), "a cycle was reported twice"
+    assert canonical(cycles) == brute_force_cycles(adjacency)
+    earliest = [min(cycle) for cycle in cycles if len(cycle) > 1]
+    assert earliest == sorted(earliest)