syntax-symphony 0.2.1__tar.gz → 0.3.0__tar.gz

{syntax_symphony-0.2.1/src/syntax_symphony.egg-info → syntax_symphony-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syntax_symphony
-Version: 0.2.1
+Version: 0.3.0
 Summary: Efficient grammar-based fuzzer.
 Author-email: Stanimir Iglev <iglev.stanimir@gmail.com>
 Maintainer-email: Stanimir Iglev <iglev.stanimir@gmail.com>
@@ -129,11 +129,14 @@ ssfuzz -g examples/expr_grammar.json -c 100 --start begin
 
 # Set the file extension
 ssfuzz -g examples/expr_grammar.json -c 100 -e json
+
+# Reproduce the same output sequence across runs
+ssfuzz -g examples/expr_grammar.json -c 100 --seed 42
 ```
 
 ### Full syntax:
 ```
-ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER]
+ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER] [--seed NUMBER]
 
 Syntax Symphony Fuzzer
 
@@ -152,6 +155,7 @@ options:
   --min-depth NUMBER    Minimum depth for the derivation trees. Default: 1
   -k NUMBER, --kcov NUMBER
                         Number of strings to generate for k-cov. Default: 1
+  --seed NUMBER         Random seed for reproducible fuzzing. Default: non-deterministic
 ```
 
 ## API
@@ -177,8 +181,8 @@ grammar = Grammar({
     "<number>": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
 })
 
-# Create the fuzzer
-fuzzer = SyntaxSymphony(grammar)
+# Create the fuzzer (pass seed=42 for reproducible output)
+fuzzer = SyntaxSymphony(grammar, seed=42)
 
 # Generate 10 test cases
 for i in range(10):
@@ -186,6 +190,8 @@ for i in range(10):
     print(test_case)
 ```
 
+Pass `seed` to get the same sequence of outputs across runs. The fuzzer uses a private `random.Random` instance, so it does not affect global random state. Omit `seed` (or pass `None`) for non-deterministic fuzzing.
+
 ## Contributing
 We welcome contributions from the community. If you have ideas for improvements, new features, or bug fixes, please submit a pull request or open an issue on our [GitHub repository](https://github.com/StanimirIglev/syntax-symphony).
 

{syntax_symphony-0.2.1 → syntax_symphony-0.3.0}/README.md

@@ -82,11 +82,14 @@ ssfuzz -g examples/expr_grammar.json -c 100 --start begin
 
 # Set the file extension
 ssfuzz -g examples/expr_grammar.json -c 100 -e json
+
+# Reproduce the same output sequence across runs
+ssfuzz -g examples/expr_grammar.json -c 100 --seed 42
 ```
 
 ### Full syntax:
 ```
-ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER]
+ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER] [--seed NUMBER]
 
 Syntax Symphony Fuzzer
 
@@ -105,6 +108,7 @@ options:
   --min-depth NUMBER    Minimum depth for the derivation trees. Default: 1
   -k NUMBER, --kcov NUMBER
                         Number of strings to generate for k-cov. Default: 1
+  --seed NUMBER         Random seed for reproducible fuzzing. Default: non-deterministic
 ```
 
 ## API
@@ -130,8 +134,8 @@ grammar = Grammar({
     "<number>": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
 })
 
-# Create the fuzzer
-fuzzer = SyntaxSymphony(grammar)
+# Create the fuzzer (pass seed=42 for reproducible output)
+fuzzer = SyntaxSymphony(grammar, seed=42)
 
 # Generate 10 test cases
 for i in range(10):
@@ -139,6 +143,8 @@ for i in range(10):
     print(test_case)
 ```
 
+Pass `seed` to get the same sequence of outputs across runs. The fuzzer uses a private `random.Random` instance, so it does not affect global random state. Omit `seed` (or pass `None`) for non-deterministic fuzzing.
+
 ## Contributing
 We welcome contributions from the community. If you have ideas for improvements, new features, or bug fixes, please submit a pull request or open an issue on our [GitHub repository](https://github.com/StanimirIglev/syntax-symphony).
 

{syntax_symphony-0.2.1 → syntax_symphony-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "syntax_symphony"
-version = "0.2.1"
+version = "0.3.0"
 description = "Efficient grammar-based fuzzer."
 readme = "README.md"
 requires-python = ">=3.12"

{syntax_symphony-0.2.1 → syntax_symphony-0.3.0}/src/syntax_symphony/cli.py

@@ -85,6 +85,15 @@ def ssfuzz() -> None:
         type=int,
         help="Number of strings to generate for k-cov. Default: 1",
     )
+    parser.add_argument(
+        "--seed",
+        dest="seed",
+        metavar="NUMBER",
+        default=None,
+        required=False,
+        type=int,
+        help="Random seed for reproducible fuzzing. Default: non-deterministic",
+    )
 
     args = parser.parse_args()
 
@@ -113,7 +122,13 @@ def ssfuzz() -> None:
         print(f"Error: {exc}", file=sys.stderr)
         sys.exit(1)
 
-    fuzzer = SyntaxSymphony(grammar, args.kcov, args.min_depth, args.max_depth)
+    fuzzer = SyntaxSymphony(
+        grammar,
+        args.kcov,
+        args.min_depth,
+        args.max_depth,
+        seed=args.seed,
+    )
 
     if not os.path.isdir(args.output_dir):
         os.makedirs(args.output_dir)

{syntax_symphony-0.2.1 → syntax_symphony-0.3.0}/src/syntax_symphony/fuzzer.py

@@ -28,6 +28,7 @@ class SyntaxSymphony:
         kcov: int = 1,
         min_depth: int = 0,
         max_depth: int = 10,
+        seed: int | None = None,
     ):
         """Initialize a fuzzer.
 
@@ -38,12 +39,15 @@ class SyntaxSymphony:
                 Defaults to 0.
             max_depth (int, optional): Maximal depth for derivation trees.
                 Defaults to 10.
+            seed (int | None, optional): Random seed for reproducible fuzzing.
+                Defaults to None (non-deterministic).
         """
         self.grammar = grammar
         self.start_symbol = grammar.start_symbol
         self._kcov = kcov
         self._min_depth = min_depth
         self._max_depth = max_depth
+        self._rng = random.Random(seed)
         self.symbol_costs: dict[str, int | float] = {}
         _logger.info("Computing costs...")
         self.costs = self.compute_cost()
@@ -56,7 +60,7 @@ class SyntaxSymphony:
         self.uncovered_k_paths = copy.deepcopy(self.k_paths)
         # NOTE: Shuffle the paths, so that we only need to pop from the list.
         for symbol in self.uncovered_k_paths:
-            random.shuffle(self.uncovered_k_paths[symbol])
+            self._rng.shuffle(self.uncovered_k_paths[symbol])
         # self.k_tree_generator = self.convert_paths_to_trees(self.k_paths)
 
     def symbol_cost(self, symbol: str, seen: set[str]) -> int | float:
@@ -352,7 +356,7 @@ class SyntaxSymphony:
                 item.children = k_tree.children
             else:
                 grammar = self._pick_grammar(depth)
-                expansion = random.choice(grammar[item.symbol])
+                expansion = self._rng.choice(grammar[item.symbol])
                 tree_expansion = [self.symbol_to_tree(t) for t in expansion]
                 item.children = tree_expansion
                 queue.extend((depth + 1, t) for t in tree_expansion)

{syntax_symphony-0.2.1 → syntax_symphony-0.3.0/src/syntax_symphony.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: syntax_symphony
-Version: 0.2.1
+Version: 0.3.0
 Summary: Efficient grammar-based fuzzer.
 Author-email: Stanimir Iglev <iglev.stanimir@gmail.com>
 Maintainer-email: Stanimir Iglev <iglev.stanimir@gmail.com>
@@ -129,11 +129,14 @@ ssfuzz -g examples/expr_grammar.json -c 100 --start begin
 
 # Set the file extension
 ssfuzz -g examples/expr_grammar.json -c 100 -e json
+
+# Reproduce the same output sequence across runs
+ssfuzz -g examples/expr_grammar.json -c 100 --seed 42
 ```
 
 ### Full syntax:
 ```
-ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER]
+ssfuzz [-h] -g FILE [-s SYMBOL] -c NUMBER [-d DIR] [-e EXT] [--max-depth NUMBER] [--min-depth NUMBER] [-k NUMBER] [--seed NUMBER]
 
 Syntax Symphony Fuzzer
 
@@ -152,6 +155,7 @@ options:
   --min-depth NUMBER    Minimum depth for the derivation trees. Default: 1
   -k NUMBER, --kcov NUMBER
                         Number of strings to generate for k-cov. Default: 1
+  --seed NUMBER         Random seed for reproducible fuzzing. Default: non-deterministic
 ```
 
 ## API
@@ -177,8 +181,8 @@ grammar = Grammar({
     "<number>": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
 })
 
-# Create the fuzzer
-fuzzer = SyntaxSymphony(grammar)
+# Create the fuzzer (pass seed=42 for reproducible output)
+fuzzer = SyntaxSymphony(grammar, seed=42)
 
 # Generate 10 test cases
 for i in range(10):
@@ -186,6 +190,8 @@ for i in range(10):
     print(test_case)
 ```
 
+Pass `seed` to get the same sequence of outputs across runs. The fuzzer uses a private `random.Random` instance, so it does not affect global random state. Omit `seed` (or pass `None`) for non-deterministic fuzzing.
+
 ## Contributing
 We welcome contributions from the community. If you have ideas for improvements, new features, or bug fixes, please submit a pull request or open an issue on our [GitHub repository](https://github.com/StanimirIglev/syntax-symphony).
 

syntax_symphony-0.3.0/tests/test_fuzzer.py

@@ -0,0 +1,230 @@
+import re
+
+import pytest
+
+from syntax_symphony.derivation_tree import DT
+from syntax_symphony.fuzzer import SyntaxSymphony
+from syntax_symphony.grammar import Grammar
+
+# --- k-path computation ---
+
+
+def test_compute_k_paths_k1(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+    paths = fuzzer._compute_k_paths(1)
+
+    assert paths["<start>"] == [[["<A>"]]]
+    assert paths["<A>"] == [[["<B>", "x"]], [["y"]]]
+    assert paths["<B>"] == [[["z"]]]
+
+
+def test_compute_k_paths_k2(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+    paths = fuzzer._compute_k_paths(2)
+
+    assert paths["<A>"] == [[["<B>", "x"], ["z"]]]
+    assert paths["<start>"] == [[["<A>"], ["<B>", "x"]], [["<A>"], ["y"]]]
+    assert paths["<B>"] == []
+
+
+def test_compute_k_paths_k3(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+    paths = fuzzer._compute_k_paths(3)
+
+    assert paths["<start>"] == [[["<A>"], ["<B>", "x"], ["z"]]]
+    assert paths["<A>"] == []
+    assert paths["<B>"] == []
+
+
+def test_compute_k_paths_accumulates_through_kcov(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=2)
+
+    assert len(fuzzer.k_paths["<start>"]) == 3
+    assert len(fuzzer.k_paths["<A>"]) == 3
+    assert len(fuzzer.k_paths["<B>"]) == 1
+
+
+def test_compute_k_paths_invalid_k(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+
+    with pytest.raises(ValueError, match="max_k must be at least 1"):
+        fuzzer.compute_k_paths(0)
+
+
+def test_terminal_only_k_paths(terminal_only_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(terminal_only_grammar, kcov=1)
+
+    assert fuzzer.k_paths == {"<start>": [[["hello"]]]}
+    assert fuzzer.remaining_k_paths() == 1
+
+
+# --- cost computation and biased grammars ---
+
+
+def test_compute_cost(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+
+    assert fuzzer.costs["<A>"] == {"<B>x": 2, "y": 1}
+    assert fuzzer.costs["<B>"] == {"z": 1}
+    assert fuzzer.costs["<start>"] == {"<A>": 2}
+
+
+def test_biased_grammar_min_max(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+
+    assert fuzzer.minimizing_grammar["<A>"] == [["y"]]
+    assert fuzzer.maximizing_grammar["<A>"] == [["<B>", "x"]]
+
+
+# --- coverage tracking ---
+
+
+def test_remaining_k_paths_initial_count(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=2, seed=42)
+
+    assert fuzzer.remaining_k_paths() == 7
+
+
+def test_k_paths_depleted_after_fuzzing(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=2, seed=42)
+    initial = fuzzer.remaining_k_paths()
+
+    for _ in range(initial):
+        fuzzer.fuzz()
+
+    assert fuzzer.remaining_k_paths() == 0
+
+
+def test_no_paths_reused_after_depletion(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=2, seed=42)
+
+    while fuzzer.remaining_k_paths() > 0:
+        fuzzer.fuzz()
+
+    for _ in range(5):
+        before = fuzzer.remaining_k_paths()
+        fuzzer.fuzz()
+        assert fuzzer.remaining_k_paths() == before == 0
+
+
+# --- depth control ---
+
+
+def test_max_depth_prefers_shallower_expansions(
+    depth_chain_grammar: Grammar,
+) -> None:
+    shallow = SyntaxSymphony(
+        depth_chain_grammar,
+        kcov=1,
+        min_depth=0,
+        max_depth=1,
+        seed=42,
+    )
+    deep = SyntaxSymphony(
+        depth_chain_grammar,
+        kcov=1,
+        min_depth=0,
+        max_depth=10,
+        seed=42,
+    )
+
+    shallow_tree = shallow.tree_fuzz(DT(shallow.start_symbol, None))
+    deep_tree = deep.tree_fuzz(DT(deep.start_symbol, None))
+
+    assert shallow_tree.height() < deep_tree.height()
+
+
+def test_min_depth_biases_toward_deeper_expansions(
+    depth_chain_grammar: Grammar,
+) -> None:
+    low_min = SyntaxSymphony(
+        depth_chain_grammar,
+        kcov=1,
+        min_depth=0,
+        max_depth=10,
+        seed=7,
+    )
+    high_min = SyntaxSymphony(
+        depth_chain_grammar,
+        kcov=1,
+        min_depth=2,
+        max_depth=10,
+        seed=7,
+    )
+
+    low_tree = low_min.tree_fuzz(DT(low_min.start_symbol, None))
+    high_tree = high_min.tree_fuzz(DT(high_min.start_symbol, None))
+
+    assert high_tree.height() >= low_tree.height()
+
+
+# --- seed reproducibility ---
+
+
+def test_same_seed_same_output(tiny_grammar: Grammar) -> None:
+    first = SyntaxSymphony(tiny_grammar, kcov=2, seed=99)
+    second = SyntaxSymphony(tiny_grammar, kcov=2, seed=99)
+
+    assert [first.fuzz() for _ in range(5)] == [second.fuzz() for _ in range(5)]
+
+
+def test_different_seed_different_output(tiny_grammar: Grammar) -> None:
+    first = SyntaxSymphony(tiny_grammar, kcov=2, seed=99)
+    second = SyntaxSymphony(tiny_grammar, kcov=2, seed=100)
+
+    assert [first.fuzz() for _ in range(5)] != [second.fuzz() for _ in range(5)]
+
+
+def test_same_seed_same_shuffle_order(tiny_grammar: Grammar) -> None:
+    first = SyntaxSymphony(tiny_grammar, kcov=2, seed=42)
+    second = SyntaxSymphony(tiny_grammar, kcov=2, seed=42)
+
+    assert first.uncovered_k_paths == second.uncovered_k_paths
+
+
+# --- helpers and edge cases ---
+
+
+def test_symbol_to_tree(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1)
+
+    nonterminal = fuzzer.symbol_to_tree("<A>")
+    terminal = fuzzer.symbol_to_tree("x")
+
+    assert nonterminal.symbol == "<A>"
+    assert nonterminal.children is None
+    assert terminal.symbol == "x"
+    assert terminal.children == []
+
+
+def test_complete_tree(tiny_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(tiny_grammar, kcov=1, seed=42)
+    partial = DT("<start>", [DT("<A>", None)])
+    completed = fuzzer.complete_tree(partial)
+
+    assert completed.to_str()
+    assert "<" not in completed.to_str()
+
+
+def test_fuzz_returns_only_terminals(expr_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(expr_grammar, kcov=1, seed=42)
+
+    for _ in range(10):
+        result = fuzzer.fuzz()
+        assert isinstance(result, str)
+        assert len(result) > 0
+        assert not re.search(r"<[^>]+>", result)
+
+
+def test_recursive_grammar_fuzz_succeeds(expr_grammar: Grammar) -> None:
+    fuzzer = SyntaxSymphony(expr_grammar, kcov=2, seed=42)
+
+    results = {fuzzer.fuzz() for _ in range(20)}
+    assert len(results) > 1
+
+
+def test_fuzz(expr_grammar: Grammar) -> None:
+    symphony = SyntaxSymphony(expr_grammar, seed=42)
+    result = symphony.fuzz()
+    assert isinstance(result, str)
+    assert len(result) > 0

syntax_symphony-0.2.1/tests/test_fuzzer.py

@@ -1,21 +0,0 @@
-from syntax_symphony.fuzzer import SyntaxSymphony
-from syntax_symphony.grammar import Grammar
-
-grammar = Grammar(
-    {
-        "<start>": ["<expr>"],
-        "<expr>": ["<term> + <expr>", "<term> - <expr>", "<term>"],
-        "<term>": ["<factor> * <term>", "<factor> / <term>", "<factor>"],
-        "<factor>": ["<number>", "( <expr> )"],
-        "<number>": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"],
-    }
-)
-
-# TODO: More tests!
-
-
-def test_fuzz():
-    symphony = SyntaxSymphony(grammar)
-    result = symphony.fuzz()
-    assert isinstance(result, str)
-    assert len(result) > 0