hints: Introduce "special" hint types (#336)

They're intended to convey information from one pass to another, but shouldn't
be attempted individually (as a matter of optimization).

For example, for the unused file removal pass other passes could emit hints with
some type like @FileRef; we shouldn't waste time deleting those file references
one-by-one.

Author: emaxx-google

cvise/passes/hint_based.py

@@ -4,7 +4,15 @@
 from typing import Any, Dict, List, Sequence, Tuple, Union
 
 from cvise.passes.abstract import AbstractPass, BinaryState, PassResult, ProcessEventNotifier
-from cvise.utils.hint import apply_hints, group_hints_by_type, HintBundle, HintApplicationStats, load_hints, store_hints
+from cvise.utils.hint import (
+    apply_hints,
+    group_hints_by_type,
+    is_special_hint_type,
+    HintBundle,
+    HintApplicationStats,
+    load_hints,
+    store_hints,
+)
 
 HINTS_FILE_NAME_TEMPLATE = 'hints{type}.jsonl.zst'
 
@@ -46,6 +54,19 @@ def advance_on_success(self, new_hint_count: int) -> Union[PerTypeHintState, Non
         )
 
 
+@dataclass(frozen=True)
+class SpecialHintState:
+    """A sub-item of HintState for "special" hint types - those that start from "@".
+
+    Such hints aren't attempted as reduction attempts themselves, instead they convey information from one pass to
+    another - hence there's no underlying_state here.
+    """
+
+    type: str
+    hints_file_name: Path
+    hint_count: int
+
+
 @dataclass(frozen=True)
 class HintState:
     """Stores the current state of the HintBasedPass.
@@ -57,21 +78,29 @@ class HintState:
     tmp_dir: Path
     # The enumeration state for each hint type. Sorted by type (in order to have deterministic and repeatable
     # enumeration order).
-    per_type_states: Tuple[PerTypeHintState]
+    per_type_states: Tuple[PerTypeHintState, ...]
     # Pointer to the current per-type state in the round-robin enumeration.
     ptr: int
+    # Information for "special" hint types (those that start with "@"). They're stored separately because we don't
+    # attempt applying them during enumeration - they're only intended as inputs for other passes that depend on them.
+    special_hints: Tuple[SpecialHintState, ...]
 
     @staticmethod
-    def create(tmp_dir: Path, per_type_states: List[PerTypeHintState]):
+    def create(tmp_dir: Path, per_type_states: List[PerTypeHintState], special_hints: List[SpecialHintState]):
         sorted_states = sorted(per_type_states, key=lambda s: s.type)
-        return HintState(tmp_dir=tmp_dir, per_type_states=tuple(sorted_states), ptr=0)
+        sorted_special_hints = sorted(special_hints, key=lambda s: s.type)
+        return HintState(
+            tmp_dir=tmp_dir, per_type_states=tuple(sorted_states), ptr=0, special_hints=tuple(sorted_special_hints)
+        )
 
     def __repr__(self):
         parts = []
         for i, s in enumerate(self.per_type_states):
             mark = '[*]' if i == self.ptr and len(self.per_type_states) > 1 else ''
             type_s = s.type + ': ' if s.type else ''
             parts.append(f'{mark}{type_s}{s.underlying_state.compact_repr()}')
+        for s in self.special_hints:
+            parts.append(f'{s.type}: {s.hint_count}')
         return f'HintState({", ".join(parts)})'
 
     def real_chunk(self) -> int:
@@ -98,7 +127,12 @@ def advance(self) -> Union[HintState, None]:
             new_ptr += 1
         new_ptr %= len(new_per_type_states)
 
-        return HintState(tmp_dir=self.tmp_dir, per_type_states=tuple(new_per_type_states), ptr=new_ptr)
+        return HintState(
+            tmp_dir=self.tmp_dir,
+            per_type_states=tuple(new_per_type_states),
+            ptr=new_ptr,
+            special_hints=self.special_hints,
+        )
 
     def advance_on_success(self, type_to_bundle: Dict[str, HintBundle]):
         sub_states = []
@@ -114,10 +148,15 @@ def advance_on_success(self, type_to_bundle: Dict[str, HintBundle]):
                 sub_states.append(new_substate)
         if not sub_states:
             return None
-        return HintState(tmp_dir=self.tmp_dir, per_type_states=tuple(sub_states), ptr=0)
+        return HintState(
+            tmp_dir=self.tmp_dir, per_type_states=tuple(sub_states), ptr=0, special_hints=self.special_hints
+        )
 
     def hint_bundle_paths(self) -> Dict[str, Path]:
-        return {substate.type: self.tmp_dir / substate.hints_file_name for substate in self.per_type_states}
+        return {
+            substate.type: self.tmp_dir / substate.hints_file_name
+            for substate in self.per_type_states + self.special_hints
+        }
 
 
 class HintBasedPass(AbstractPass):
@@ -186,6 +225,8 @@ def new(
         return self.new_from_hints(hints, tmp_dir)
 
     def transform(self, test_case: Path, state: HintState, original_test_case: Path, *args, **kwargs):
+        if not state.per_type_states:  # possible if all hints produced by new() were "special"
+            return PassResult.STOP, state
         self.load_and_apply_hints(original_test_case, test_case, [state])
         return PassResult.OK, state
 
@@ -230,18 +271,27 @@ def new_from_hints(self, bundle: HintBundle, tmp_dir: Path) -> Union[HintState,
         type_to_bundle = group_hints_by_type(bundle)
         self.backfill_pass_names(type_to_bundle)
         type_to_file_name = store_hints_per_type(tmp_dir, type_to_bundle)
-        sub_states = []
-        # Initialize a separate enumeration for each group of hints sharing a particular type.
+        sub_states: List[PerTypeHintState] = []
+        special_states: List[SpecialHintState] = []
         for type, sub_bundle in type_to_bundle.items():
-            underlying = self.create_elementary_state(len(sub_bundle.hints))
-            if underlying is None:
-                continue
-            sub_states.append(
-                PerTypeHintState(type=type, hints_file_name=type_to_file_name[type], underlying_state=underlying)
-            )
-        if not sub_states:
+            if is_special_hint_type(type):
+                # "Special" hints aren't attempted in transform() jobs - only store them to be consumed by other passes.
+                special_states.append(
+                    SpecialHintState(
+                        type=type, hints_file_name=type_to_file_name[type], hint_count=len(sub_bundle.hints)
+                    )
+                )
+            else:
+                # Initialize a separate enumeration for this group of hints sharing a particular type.
+                underlying = self.create_elementary_state(len(sub_bundle.hints))
+                if underlying is None:
+                    continue
+                sub_states.append(
+                    PerTypeHintState(type=type, hints_file_name=type_to_file_name[type], underlying_state=underlying)
+                )
+        if not sub_states and not special_states:
             return None
-        return HintState.create(tmp_dir, sub_states)
+        return HintState.create(tmp_dir, sub_states, special_states)
 
     def advance_on_success_from_hints(self, bundle: HintBundle, state: HintState) -> Union[HintState, None]:
         """Advances the state after a successful reduction, given pre-generated hints.

cvise/tests/test_folding.py

@@ -12,6 +12,7 @@ def create_stub_hint_state(type: str) -> HintState:
         tmp_dir=fake_path,
         per_type_states=(PerTypeHintState(type=type, hints_file_name=fake_path, underlying_state=underlying_state),),
         ptr=0,
+        special_hints=(),
     )
 
 

cvise/tests/test_hint_based.py

@@ -3,7 +3,7 @@
 
 from cvise.passes.hint_based import HintBasedPass
 from cvise.tests.testabstract import collect_all_transforms, iterate_pass, validate_hint_bundle
-from cvise.utils.hint import HintBundle
+from cvise.utils.hint import HintBundle, load_hints
 from cvise.utils.process import ProcessEventNotifier
 
 
@@ -216,3 +216,50 @@ def test_hint_based_non_utf8(tmp_path: Path):
     assert b'f\0oo\xc3\x84' in all_transforms  # hint34 applied
     assert b'f\0o\xffo' in all_transforms  # hint57 applied
     assert b'fo' in all_transforms  # all applied
+
+
+def test_hint_based_special_hints_not_attempted(tmp_path: Path):
+    """Test that special hints (whose type starts from "@") aren't attempted in the pass transform() calls."""
+    input = b'foo'
+    test_case = tmp_path / 'input.txt'
+    vocab = ['sometype', '@specialtype']
+    hint_regular = {'t': 0, 'p': [{'l': 0, 'r': 1}]}
+    hint_special = {'t': 1, 'p': [{'l': 1, 'r': 2}]}
+    pass_ = StubHintBasedPass(
+        {
+            input: [hint_regular, hint_special],
+        },
+        vocabulary=vocab,
+    )
+    test_case.write_bytes(input)
+
+    state = pass_.new(test_case, tmp_dir=tmp_path, process_event_notifier=ProcessEventNotifier(None), dependee_hints=[])
+    all_transforms = collect_all_transforms(pass_, state, test_case)
+    assert b'oo' in all_transforms  # hint_regular applied
+    assert b'fo' not in all_transforms  # hint_special not applied
+
+
+def test_hint_based_special_hints_stored(tmp_path: Path):
+    """Test that special hints produced by a pass are stored on disk, even if no other hints are produced."""
+    input = b'foo'
+    test_case = tmp_path / 'input.txt'
+    hint_type = '@specialtype'
+    hint = {'t': 0, 'p': [{'l': 1, 'r': 2}]}
+    pass_ = StubHintBasedPass(
+        {
+            input: [hint],
+        },
+        vocabulary=[hint_type],
+    )
+    test_case.write_bytes(input)
+
+    state = pass_.new(test_case, tmp_dir=tmp_path, process_event_notifier=ProcessEventNotifier(None), dependee_hints=[])
+    assert state is not None
+    bundle_paths = state.hint_bundle_paths()
+    assert len(bundle_paths) == 1
+    assert hint_type in bundle_paths
+    bundle = load_hints(bundle_paths[hint_type], begin_index=None, end_index=None)
+    assert bundle.hints == [hint]
+
+    all_transforms = collect_all_transforms(pass_, state, test_case)
+    assert all_transforms == set()

cvise/tests/testabstract.py

@@ -30,11 +30,14 @@ def collect_all_transforms(pass_: AbstractPass, state, input_path: Path) -> Set[
         tmp_path = Path(tmp_file.name)
         tmp_file.close()
         while state is not None:
-            pass_.transform(
+            result, _new_state = pass_.transform(
                 tmp_path, state, process_event_notifier=ProcessEventNotifier(None), original_test_case=input_path
             )
-            all_outputs.add(tmp_path.read_bytes())
-            state = pass_.advance(input_path, state)
+            if result == PassResult.OK:
+                all_outputs.add(tmp_path.read_bytes())
+                state = pass_.advance(input_path, state)
+            elif result == PassResult.STOP:
+                break
     return all_outputs
 
 
@@ -43,14 +46,17 @@ def collect_all_transforms_dir(pass_: AbstractPass, state, input_path: Path) ->
     while state is not None:
         with tempfile.TemporaryDirectory() as tmp_dir:
             tmp_path = Path(tmp_dir)
-            pass_.transform(
+            result, _new_state = pass_.transform(
                 tmp_path, state, process_event_notifier=ProcessEventNotifier(None), original_test_case=input_path
             )
-            contents = tuple(
-                sorted((str(p.relative_to(tmp_dir)), p.read_bytes()) for p in tmp_path.rglob('*') if not p.is_dir())
-            )
-            all_outputs.add(contents)
-            state = pass_.advance(input_path, state)
+            if result == PassResult.OK:
+                contents = tuple(
+                    sorted((str(p.relative_to(tmp_dir)), p.read_bytes()) for p in tmp_path.rglob('*') if not p.is_dir())
+                )
+                all_outputs.add(contents)
+                state = pass_.advance(input_path, state)
+            elif result == PassResult.STOP:
+                break
     return all_outputs
 
 

cvise/utils/hint.py

@@ -89,9 +89,11 @@ class HintBundle:
         },
         't': {
             'description': (
-                'Indicates the type of the hint, as an index in the vocabulary. The purpose of the type is to let a '
-                'pass split hints into distinct groups, to guide the generic logic that attempts taking consecutive '
-                'ranges of same-typed hints.'
+                'Indicates the type of the hint, as an index in the vocabulary. Types starting from "@" (the at sign) '
+                'have special meaning - such hints are not attempted as reduction transformations, but are only '
+                'intended to be consumed by other passes as input data. Types not starting from "@" are just used as a '
+                'way to split hints from a particular pass into distinct groups, to guide the generic logic that '
+                'attempts taking consecutive ranges of same-typed hints.'
             ),
             'type': 'integer',
             'minimum': 0,
@@ -118,6 +120,10 @@ def get_passes_ordered_by_delta(self) -> List[str]:
 json_encoder: Union[msgspec.json.Encoder, None] = None
 
 
+def is_special_hint_type(type: str) -> bool:
+    return type.startswith('@')
+
+
 def apply_hints(bundles: List[HintBundle], source_path: Path, destination_path: Path) -> HintApplicationStats:
     """Creates the destination file/dir by applying the specified hints to the contents of the source file/dir."""
     # Take patches from all hints and group them by the file which they're applied to.