feat(detect): add declaration-scoped # noqa: codeclone[dead-code] suppressions (parser, symbol binding, final filtering) with tests and docs; update html-report UI

Author: orenlab

CHANGELOG.md

@@ -118,6 +118,12 @@ ahead of the final `2.0.0` release.
   production symbols used only in tests are still reported as dead-code candidates.
 - Dead-code liveness now uses exact canonical qualname references (including import-alias and module-alias usage)
   before fallback local-name checks, reducing false positives on re-export and alias wiring.
+- Added declaration-scoped inline suppressions for accepted dead-code findings:
+    - `# noqa: codeclone[dead-code]` on `def`, `async def`, or `class`
+    - supports both previous-line and end-of-line forms on declaration lines
+    - suppression is target-scoped (does not cascade to unrelated symbols)
+- Added deterministic suppression parser/binder (`codeclone/suppressions.py`) and integrated suppression metadata into
+  dead-code candidate processing and cache payloads (backward-compatible decode for legacy cache rows).
 - Refactored `scanner.iter_py_files` into deterministic helpers without semantic changes, reducing method complexity and
   keeping metrics-gate parity with the baseline.
 

README.md

@@ -80,6 +80,27 @@ codeclone . --fail-cycles --fail-dead-code
 codeclone . --fail-on-new-metrics
 ```
 
+### Inline Suppressions For Known FP
+
+Use local declaration-level suppressions when a finding is accepted by design
+(for example runtime callbacks invoked by a framework):
+
+```python
+# noqa: codeclone[dead-code]
+def handle_exception(exc: Exception) -> None:
+    ...
+
+class Middleware:  # noqa: codeclone[dead-code]
+    ...
+```
+
+Rules:
+
+- supports `def`, `async def`, and `class`
+- supports previous-line and end-of-line forms on declaration lines
+- requires explicit rule list: `codeclone[...]`
+- does not provide file-level/global ignores
+
 ### Pre-commit
 
 ```yaml
@@ -154,6 +175,9 @@ Structural findings include:
 - `clone_guard_exit_divergence`
 - `clone_cohort_drift`
 
+Dead-code detection is intentionally deterministic and static. Dynamic/runtime false positives are resolved
+via explicit inline suppressions, not via broad heuristics or implicit framework-specific guesses.
+
 <details>
 <summary>JSON report shape (v2.1)</summary>
 
@@ -265,7 +289,7 @@ Architecture: [`docs/architecture.md`](docs/architecture.md) · CFG semantics: [
 | Docker benchmark contract  | [`docs/book/18-benchmarking.md`](docs/book/18-benchmarking.md)                           |
 | Determinism                | [`docs/book/12-determinism.md`](docs/book/12-determinism.md)                             |
 
-##  * Benchmarking
+##   * Benchmarking
 
 <details>
 <summary>Reproducible Docker Benchmark</summary>

codeclone/cache.py

@@ -92,7 +92,7 @@ class ModuleDepDict(TypedDict):
     line: int
 
 
-class DeadCandidateDict(TypedDict):
+class DeadCandidateDictBase(TypedDict):
     qualname: str
     local_name: str
     filepath: str
@@ -101,6 +101,10 @@ class DeadCandidateDict(TypedDict):
     kind: str
 
 
+class DeadCandidateDict(DeadCandidateDictBase, total=False):
+    suppressed_rules: list[str]
+
+
 class StructuralFindingOccurrenceDict(TypedDict):
     qualname: str
     start: int
@@ -1041,14 +1045,17 @@ def _dead_candidate_dict_from_model(
     candidate: DeadCandidate,
     filepath: str,
 ) -> DeadCandidateDict:
-    return DeadCandidateDict(
+    result = DeadCandidateDict(
         qualname=candidate.qualname,
         local_name=candidate.local_name,
         filepath=filepath,
         start_line=candidate.start_line,
         end_line=candidate.end_line,
         kind=candidate.kind,
     )
+    if candidate.suppressed_rules:
+        result["suppressed_rules"] = sorted(set(candidate.suppressed_rules))
+    return result
 
 
 def _structural_occurrence_dict_from_model(
@@ -1203,14 +1210,32 @@ def _canonicalize_cache_entry(entry: CacheEntry) -> CacheEntry:
             item["line"],
         ),
     )
+    dead_candidates_normalized: list[DeadCandidateDict] = []
+    for candidate in entry["dead_candidates"]:
+        suppressed_rules = candidate.get("suppressed_rules", [])
+        normalized_candidate = DeadCandidateDict(
+            qualname=candidate["qualname"],
+            local_name=candidate["local_name"],
+            filepath=candidate["filepath"],
+            start_line=candidate["start_line"],
+            end_line=candidate["end_line"],
+            kind=candidate["kind"],
+        )
+        if _is_string_list(suppressed_rules):
+            normalized_rules = sorted(set(suppressed_rules))
+            if normalized_rules:
+                normalized_candidate["suppressed_rules"] = normalized_rules
+        dead_candidates_normalized.append(normalized_candidate)
+
     dead_candidates_sorted = sorted(
-        entry["dead_candidates"],
+        dead_candidates_normalized,
         key=lambda item: (
             item["start_line"],
             item["end_line"],
             item["qualname"],
             item["local_name"],
             item["kind"],
+            tuple(item.get("suppressed_rules", [])),
         ),
     )
 
@@ -1803,13 +1828,19 @@ def _decode_wire_dead_candidate(
     filepath: str,
 ) -> DeadCandidateDict | None:
     row = _as_list(value)
-    if row is None or len(row) != 5:
+    if row is None or len(row) not in {5, 6}:
         return None
     qualname = _as_str(row[0])
     local_name = _as_str(row[1])
     start_line = _as_int(row[2])
     end_line = _as_int(row[3])
     kind = _as_str(row[4])
+    suppressed_rules: list[str] | None = []
+    if len(row) == 6:
+        raw_rules = _as_list(row[5])
+        if raw_rules is None or not all(isinstance(rule, str) for rule in raw_rules):
+            return None
+        suppressed_rules = sorted({str(rule) for rule in raw_rules if str(rule)})
     if (
         qualname is None
         or local_name is None
@@ -1818,14 +1849,17 @@ def _decode_wire_dead_candidate(
         or kind is None
     ):
         return None
-    return DeadCandidateDict(
+    decoded = DeadCandidateDict(
         qualname=qualname,
         local_name=local_name,
         filepath=filepath,
         start_line=start_line,
         end_line=end_line,
         kind=kind,
     )
+    if suppressed_rules:
+        decoded["suppressed_rules"] = suppressed_rules
+    return decoded
 
 
 def _encode_wire_file_entry(entry: CacheEntry) -> dict[str, object]:
@@ -1980,16 +2014,22 @@ def _encode_wire_file_entry(entry: CacheEntry) -> dict[str, object]:
     if dead_candidates:
         # Dead candidates are stored inside a per-file cache entry, so the
         # filepath is implicit and does not need to be repeated in every row.
-        wire["dc"] = [
-            [
+        encoded_dead_candidates: list[list[object]] = []
+        for candidate in dead_candidates:
+            encoded = [
                 candidate["qualname"],
                 candidate["local_name"],
                 candidate["start_line"],
                 candidate["end_line"],
                 candidate["kind"],
             ]
-            for candidate in dead_candidates
-        ]
+            suppressed_rules = candidate.get("suppressed_rules", [])
+            if _is_string_list(suppressed_rules):
+                normalized_rules = sorted(set(suppressed_rules))
+                if normalized_rules:
+                    encoded.append(normalized_rules)
+            encoded_dead_candidates.append(encoded)
+        wire["dc"] = encoded_dead_candidates
 
     if entry["referenced_names"]:
         wire["rn"] = sorted(set(entry["referenced_names"]))
@@ -2135,11 +2175,16 @@ def _is_module_dep_dict(value: object) -> bool:
 def _is_dead_candidate_dict(value: object) -> bool:
     if not isinstance(value, dict):
         return False
-    return _has_typed_fields(
+    if not _has_typed_fields(
         value,
         string_keys=("qualname", "local_name", "filepath", "kind"),
         int_keys=("start_line", "end_line"),
-    )
+    ):
+        return False
+    suppressed_rules = value.get("suppressed_rules")
+    if suppressed_rules is None:
+        return True
+    return _is_string_list(suppressed_rules)
 
 
 def _is_string_list(value: object) -> bool:

codeclone/extractor.py

@@ -42,9 +42,18 @@
 )
 from .paths import is_test_filepath
 from .structural_findings import scan_function_structure
+from .suppressions import (
+    DeclarationTarget,
+    bind_suppressions_to_declarations,
+    build_suppression_index,
+    extract_noqa_directives,
+    suppression_target_key,
+)
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
+    from collections.abc import Iterator, Mapping
+
+    from .suppressions import SuppressionTargetKey
 
 __all__ = [
     "Unit",
@@ -472,6 +481,8 @@ def _collect_dead_candidates(
     protocol_module_aliases: frozenset[str] = frozenset(
         {"typing", "typing_extensions"}
     ),
+    suppression_rules_by_target: Mapping[SuppressionTargetKey, tuple[str, ...]]
+    | None = None,
 ) -> tuple[DeadCandidate, ...]:
     protocol_class_qualnames = {
         class_qualname
@@ -484,6 +495,9 @@ def _collect_dead_candidates(
     }
 
     candidates: list[DeadCandidate] = []
+    suppression_index = (
+        suppression_rules_by_target if suppression_rules_by_target is not None else {}
+    )
     for local_name, node in collector.units:
         start = int(getattr(node, "lineno", 0))
         end = int(getattr(node, "end_lineno", 0))
@@ -506,6 +520,16 @@ def _collect_dead_candidates(
                 start_line=start,
                 end_line=end,
                 kind=kind,
+                suppressed_rules=suppression_index.get(
+                    suppression_target_key(
+                        filepath=filepath,
+                        qualname=f"{module_name}:{local_name}",
+                        start_line=start,
+                        end_line=end,
+                        kind=kind,
+                    ),
+                    (),
+                ),
             )
         )
 
@@ -522,6 +546,16 @@ def _collect_dead_candidates(
                 start_line=start,
                 end_line=end,
                 kind="class",
+                suppressed_rules=suppression_index.get(
+                    suppression_target_key(
+                        filepath=filepath,
+                        qualname=f"{module_name}:{class_qualname}",
+                        start_line=start,
+                        end_line=end,
+                        kind="class",
+                    ),
+                    (),
+                ),
             )
         )
 
@@ -538,6 +572,61 @@ def _collect_dead_candidates(
     )
 
 
+def _collect_declaration_targets(
+    *,
+    filepath: str,
+    module_name: str,
+    collector: _QualnameCollector,
+) -> tuple[DeclarationTarget, ...]:
+    declarations: list[DeclarationTarget] = []
+
+    for local_name, node in collector.units:
+        start = int(getattr(node, "lineno", 0))
+        end = int(getattr(node, "end_lineno", 0))
+        if start <= 0 or end <= 0:
+            continue
+        kind: Literal["function", "method"] = (
+            "method" if "." in local_name else "function"
+        )
+        declarations.append(
+            DeclarationTarget(
+                filepath=filepath,
+                qualname=f"{module_name}:{local_name}",
+                start_line=start,
+                end_line=end,
+                kind=kind,
+            )
+        )
+
+    for class_qualname, class_node in collector.class_nodes:
+        start = int(getattr(class_node, "lineno", 0))
+        end = int(getattr(class_node, "end_lineno", 0))
+        if start <= 0 or end <= 0:
+            continue
+        declarations.append(
+            DeclarationTarget(
+                filepath=filepath,
+                qualname=f"{module_name}:{class_qualname}",
+                start_line=start,
+                end_line=end,
+                kind="class",
+            )
+        )
+
+    return tuple(
+        sorted(
+            declarations,
+            key=lambda item: (
+                item.filepath,
+                item.start_line,
+                item.end_line,
+                item.qualname,
+                item.kind,
+            ),
+        )
+    )
+
+
 # =========================
 # Public API
 # =========================
@@ -582,6 +671,17 @@ def extract_units_and_stats_from_source(
         collector=collector,
         collect_referenced_names=not is_test_file,
     )
+    noqa_directives = extract_noqa_directives(source)
+    declaration_targets = _collect_declaration_targets(
+        filepath=filepath,
+        module_name=module_name,
+        collector=collector,
+    )
+    suppression_bindings = bind_suppressions_to_declarations(
+        directives=noqa_directives,
+        declarations=declaration_targets,
+    )
+    suppression_index = build_suppression_index(suppression_bindings)
     protocol_symbol_aliases, protocol_module_aliases = _collect_protocol_aliases(tree)
     class_names = frozenset(class_node.name for _, class_node in collector.class_nodes)
     module_import_names = set(import_names)
@@ -721,6 +821,7 @@ def extract_units_and_stats_from_source(
         collector=collector,
         protocol_symbol_aliases=protocol_symbol_aliases,
         protocol_module_aliases=protocol_module_aliases,
+        suppression_rules_by_target=suppression_index,
     )
 
     sorted_class_metrics = tuple(