sieve-scope 1.3.0__py3-none-any.whl

sieve_scope-1.3.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: sieve-scope
+Version: 1.3.0
+Summary: Deterministic and Explainable Code Plagiarism Detection Engine with 7-bit Observation Space
+Author: Kai IWASAKI
+License: MIT
+Project-URL: Homepage, https://github.com/neguseatama/sieve-scope
+Project-URL: Repository, https://github.com/neguseatama/sieve-scope.git
+Project-URL: Bug Tracker, https://github.com/neguseatama/sieve-scope/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Sieve Scope v1.3
+
+**English** | [日本語](README.ja.md)
+
+> **"See through the formatting, and look into the pure logic of the algorithm."**
+> A fully local, zero-dependency, deterministic (100% reproducible) code plagiarism and structural similarity detection engine.
+> Extends [Sieve-Core](https://github.com/neguseatama/sieve-core)'s deterministic similarity engine and [Sieve-Referee](https://github.com/neguseatama/sieve-referee)'s multi-hypothesis LUT judgment philosophy to the **source code domain**.
+
+[![CI](https://github.com/neguseatama/sieve-scope/actions/workflows/test.yml/badge.svg)](https://github.com/neguseatama/sieve-scope/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+
+---
+
+## 💡 Concept & Philosophy
+
+The starting point of this project is **Sieve-Core**, a core engine that applies the "sieve of set theory" design philosophy of **Sieve-AI**—inspired by the Sieve of Eratosthenes—to the more general domain of text and data processing.
+
+Next, **Sieve Referee**, which adds a "sieve of combinatorics" to Sieve-Core, is a zero-dependency Python library that extracts reliable information from noise based on corroboration from multiple independent sources.
+
+Then, **Sieve Scope** further adds a two-axis evaluation and redesigns the approach, making it an explainable code plagiarism detection engine that observes the **surface format** (variable names, comments, whitespace) and the **essential logic** (algorithm structure) separately.
+
+Traditional string comparison and simple similarity measures struggle to distinguish between:
+- Plagiarism by merely renaming variables (**variable laundering**)
+- Coincidental matches due to shared templates (**boilerplate**)
+
+`Sieve Scope` observes two axes independently:
+- **AST (Abstract Syntax Tree)** — extracting the "logic skeleton" with identifiers removed
+- **tokenize** — extracting "identifier vocabulary and order"
+
+By inheriting the hypothesis mask (H1–H7) and LUT from Sieve-Referee, it fully explains why a judgment was made.
+
+> The name "Sieve Scope" comes from the design philosophy of seeing through the surface of code (format) and comparing only the pure logic, like a microscope.
+
+---
+
+## 🔥 Key Features
+
+- **7-bit Observation Space (H1–H7)**  
+  Independently evaluates AST skeleton, identifier vocabulary, positional/order (g_POS), constants (g_CONST), and vocabulary context (g_FREQ).
+- **v0_mask compatibility**  
+  The legacy 4-bit v0_mask is preserved and regression-tested.
+- **Strict Cluster Safety Invariant**  
+  H4 is promoted to 1 only when the cluster size is at least 3 **and** there is direct similarity evidence (H2∨H3). Indirect "telephone game" chains are never mixed into direct judgments.
+- **Short-Circuit Optimization**  
+  Pairs with no structural or vocabulary similarity (H2=0 ∧ H3=0) are immediately returned as `1000-000`, skipping expensive hash computations.
+- **Zero Dependencies & Deterministic**  
+  Implemented using only the Python standard library. No external packages, no API costs, no probabilistic elements.
+
+---
+
+## 📐 7-bit Observation Space
+
+The evaluation function `f_v1.3(C1, C2)` projects a code pair into seven boolean hypotheses `(H1, H2, H3, H4, H5, H6, H7)`.
+
+| Hypothesis | Name | What it measures | Criterion / Threshold |
+| :--- | :--- | :--- | :--- |
+| **H1** | Parseability | Can both be parsed as Python syntax? | Success/failure of AST construction |
+| **H2** | AST Skeleton | Do the AST node type sequences match exactly? | Exact match of skeleton strings |
+| **H3** | Identifier Similarity | Jaccard + sequence similarity of identifiers | Score `> 0.50` |
+| **H4** | Cluster Safety | Direct similarity + membership in a valid cluster (size ≥3) | Invariant condition satisfied |
+| **H5** | g_POS | SHA-256 hash of recursive AST field representation | Exact hash match |
+| **H6** | g_CONST | Constants / literals set match | Sorted constant list exact match |
+| **H7** | g_FREQ | Weighted identifier bi-gram Dice coefficient | Score `>= 0.60` |
+
+Mask notation is `v0_mask (4-bit) - extension (3-bit)`.
+Example: `1100-011` → H1=1, H2=1, H3=0, H4=0 / H5=0, H6=1, H7=1
+
+---
+
+## 📊 Representative LUT Patterns
+
+| v0_mask | Extended Example | Judgment Label | Description |
+|:---:|:---:|:---|:---|
+| `1110` | `1110-111` | `EXACT_CLONE` | Observation-space exact match |
+| `1100` | `1100-110` | `VARIABLE_LAUNDERING` | Logic matches but surface differs |
+| `1010` | `1010-011` | `COINCIDENTAL_FRAMEWORK_MATCH` | Logic differs but surface matches |
+| `1000` | `1000-000` | `INDEPENDENT_LOGIC` | No direct similarity (short-circuit) |
+| `1110` | `1110-101` | `CONSTANT_MODIFIED_CLONE` | Only constants differ |
+| `1110` | `1110-011` | `PERMUTATED_CLONE` | Non-commutative order reversed |
+
+---
+
+## 💻 Quick Start
+
+```python
+from sieve_scope import SieveScopeEngineV1_3, SieveClusterAnalyzerV1_3
+
+engine = SieveScopeEngineV1_3(jaccard_threshold=0.50, freq_dice_threshold=0.60)
+
+code_a = "def calc_sum(a, b):\n    return a + b"
+code_b = "def calc_sum(x, y):\n    return x + y"
+
+result = engine.evaluate_pair(code_a, code_b)
+
+print(result["v0_mask"])   # e.g., 1100
+print(result["mask"])      # e.g., 1100-110
+
+---
+
+### Configuration / Thresholds
+
+- `jaccard_threshold` (default: `0.50`): Threshold for H3 Multiset Jaccard + sequence similarity.
+- `freq_dice_threshold` (default: `0.60`): Threshold for H7 Weighted identifier bi-gram Dice coefficient.
+
+> **Note on Calibration & Defaults (v1.3)**:
+> Exhaustive grid search experiments on synthetic benchmark datasets demonstrate optimal class separation ($F1 = 1.0000$) across a wide threshold range of `0.35` to `0.75`. However, the default threshold parameters are strictly maintained at **`0.50` / `0.60`** in order to preserve backwards compatibility with v0, maintain regression test stability, and prevent potential false positives caused by shared domain vocabulary in production codebases.
+
+---
+
+## 🔬 Testing & Verification
+Cross-Python Validation Summary
+24 regression cases (test_v1_3_full_suite.py): PASSED
+
+5 compatibility tests (test_v1_3_regression.py): PASSED
+
+6 edge-case & parallel determinism tests (test_v1_3_edge_cases.py): PASSED
+
+81 synthetic threshold configurations (threshold_tuning.py): PASSED
+
+All test suites and synthetic experiments passed completely without errors across Python 3.9, 3.10, 3.11, and 3.12.
+
+Threshold Calibration & Synthetic Validation
+The threshold parameters (H3 Multiset Jaccard: 0.50, H7 Weighted Bi-gram Dice: 0.60) were designed and calibrated using a synthetic validation pair set (Positive 6 pairs / Negative 3 pairs).
+The engine's 1110-111 indicates an exact match in the current 7-dimensional observation space (Observation Clones), and does not guarantee complete semantic equivalence (Semantic Clones).
+
+---
+
+## 📚 Documentation
+
+- 🏛️ Architecture Specification
+
+- 🔌 API & Integration Guide
+
+- 🚀 Deployment Guide
+
+- 🔐 CI/CD & Security Guide
+
+## 📄 License
+MIT License. See LICENSE for details.
+
+## 👤 Author
+Kai IWASAKI

sieve_scope-1.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+sieve_scope.py,sha256=xts1AlZ9csOvbg8aCz8X-n26nBG2oFbjnSQi5Cg7Rfs,12871
+sieve_scope-1.3.0.dist-info/licenses/LICENSE,sha256=gkCel7djhBCn21V3Nwq1EM5HN6y53y-xoNZ3fRsfz5Y,1067
+sieve_scope-1.3.0.dist-info/METADATA,sha256=V2EP_sgXTxSD5eiO2pYtdc3T9ORZGIW1Sp4uXR4yBuo,8313
+sieve_scope-1.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sieve_scope-1.3.0.dist-info/top_level.txt,sha256=4PpNdcIQ5n6Bfc9wqsyuDfzitVcIGwpRh0yaBhBhl10,12
+sieve_scope-1.3.0.dist-info/RECORD,,

sieve_scope-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sieve_scope-1.3.0.dist-info/licenses/LICENSE

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

sieve_scope-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sieve_scope

sieve_scope.py

@@ -0,0 +1,326 @@
+"""
+Sieve Scope Engine v1.3 (Production Ready)
+- 7-bit Observation Space (H1 - H7)
+- Short-Circuit Evaluation
+- Tokenize-based Pure Identifier Extraction
+- Weighted Bi-gram Dice Coefficient
+- Parallel Pair Evaluation
+- Indirect Chain Detection
+"""
+
+import ast
+import difflib
+import hashlib
+import io
+import keyword
+import tokenize
+from collections import Counter, defaultdict, deque
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import Any, Dict, List, Set, Tuple, Optional
+
+# v0完全互換の除外識別子集合
+IGNORED_WORDS_V0: Set[str] = {
+    'print', 'len', 'range', 'sum', 'int', 'str', 'self', '__init__'
+}
+
+
+def extract_pure_identifiers(code: str, ignored_words: Set[str] = IGNORED_WORDS_V0) -> List[str]:
+    """
+    v0完全互換: tokenizeベースで非キーワードNAMEトークンを順序通り抽出する。
+    関数名・クラス名・変数名・属性名をすべて識別子として捕捉する。
+    """
+    identifiers = []
+    try:
+        tokens = tokenize.generate_tokens(io.StringIO(code).readline)
+        for toknum, tokval, _, _, _ in tokens:
+            if toknum == tokenize.NAME and not keyword.iskeyword(tokval):
+                if tokval not in ignored_words:
+                    identifiers.append(tokval)
+    except Exception:
+        pass
+    return identifiers
+
+
+def build_pos_tuple(node: Any) -> Any:
+    """
+    v1.2完全互換: ASTフィールド構造タプルを生成する。
+    value / id / attr フィールドのうち非AST値（定数・識別子名）は除外するが、
+    arg などのその他スカラーフィールドは保持する。
+    """
+    if not isinstance(node, ast.AST):
+        if isinstance(node, list):
+            return tuple(build_pos_tuple(x) for x in node)
+        return str(node)
+
+    field_tuples = []
+    for field, value in ast.iter_fields(node):
+        if field in ("value", "id", "attr") and not isinstance(value, ast.AST):
+            continue
+        field_tuples.append((field, build_pos_tuple(value)))
+    return (type(node).__name__, tuple(field_tuples))
+
+
+class ASTSkeletonVisitor(ast.NodeVisitor):
+    """
+    H2: AST構造骨格の抽出。
+    generic_visit はすべてのノード型名を記録する（Load, Store, Del, 演算子ノードを含む）。
+    """
+    def __init__(self):
+        self.skeleton = []
+
+    def generic_visit(self, node):
+        self.skeleton.append(type(node).__name__)
+        super().generic_visit(node)
+
+
+class ASTConstantVisitor(ast.NodeVisitor):
+    """H6: g_CONST 定数・リテラルの抽出"""
+    def __init__(self):
+        self.constants = []
+
+    def visit_Constant(self, node):
+        self.constants.append(str(node.value))
+        self.generic_visit(node)
+
+
+class SieveScopeEngineV1_3:
+    """7次元観測空間評価エンジン"""
+
+    def __init__(self, jaccard_threshold: float = 0.50, freq_dice_threshold: float = 0.60):
+        self.jaccard_threshold = jaccard_threshold
+        self.freq_dice_threshold = freq_dice_threshold
+
+    def evaluate_pair(self, code1: str, code2: str) -> Dict[str, Any]:
+        # H1: Parseability
+        try:
+            tree1 = ast.parse(code1)
+            tree2 = ast.parse(code2)
+            h1 = 1
+        except Exception:
+            return {
+                "h_states": {"H1": 0, "H2": 0, "H3": 0, "H4": 0, "H5": 0, "H6": 0, "H7": 0},
+                "v0_mask": "0000",
+                "mask": "0000-000",
+                "short_circuited": True,
+            }
+
+        # H2: AST Skeleton（全ノード型の列を比較）
+        vis1, vis2 = ASTSkeletonVisitor(), ASTSkeletonVisitor()
+        vis1.visit(tree1)
+        vis2.visit(tree2)
+        skeleton1 = "_".join(vis1.skeleton)
+        skeleton2 = "_".join(vis2.skeleton)
+        h2 = 1 if skeleton1 == skeleton2 else 0
+
+        # H3: 純粋識別子の類似度（Multiset Jaccard + SequenceMatcher）
+        ids1 = extract_pure_identifiers(code1)
+        ids2 = extract_pure_identifiers(code2)
+
+        if not ids1 and not ids2:
+            h3_score = 1.0
+        elif not ids1 or not ids2:
+            h3_score = 0.0
+        else:
+            c1, c2 = Counter(ids1), Counter(ids2)
+            intersection = sum((c1 & c2).values())
+            union = sum((c1 | c2).values())
+            multiset_jaccard = intersection / union if union > 0 else 0.0
+
+            seq_ratio = difflib.SequenceMatcher(None, ids1, ids2).ratio()
+            h3_score = 0.6 * multiset_jaccard + 0.4 * seq_ratio
+
+        # v0互換: 厳密な '>' 判定
+        h3 = 1 if h3_score > self.jaccard_threshold else 0
+
+        # ショートサーキット: H2=0 かつ H3=0 の場合のみ高コスト計算をスキップ
+        if h2 == 0 and h3 == 0:
+            return {
+                "h_states": {"H1": 1, "H2": 0, "H3": 0, "H4": 0, "H5": 0, "H6": 0, "H7": 0},
+                "v0_mask": "1000",
+                "mask": "1000-000",
+                "short_circuited": True,
+                "scores": {"h3_score": h3_score},
+            }
+
+        # H5: g_POS（build_pos_tuple による決定論的ハッシュ）
+        pos_tuple1 = build_pos_tuple(tree1)
+        pos_tuple2 = build_pos_tuple(tree2)
+        pos_hash1 = hashlib.sha256(str(pos_tuple1).encode('utf-8')).hexdigest()
+        pos_hash2 = hashlib.sha256(str(pos_tuple2).encode('utf-8')).hexdigest()
+        h5 = 1 if pos_hash1 == pos_hash2 else 0
+
+        # H6: g_CONST（定数集合の一致）
+        c_vis1, c_vis2 = ASTConstantVisitor(), ASTConstantVisitor()
+        c_vis1.visit(tree1)
+        c_vis2.visit(tree2)
+        h6 = 1 if sorted(c_vis1.constants) == sorted(c_vis2.constants) else 0
+
+        # H7: g_FREQ（重み付き Bi-gram Dice 係数）
+        bigrams1 = self._get_weighted_bigrams(ids1)
+        bigrams2 = self._get_weighted_bigrams(ids2)
+
+        common_keys = set(bigrams1.keys()) & set(bigrams2.keys())
+        common_weight = sum(min(bigrams1[bg], bigrams2[bg]) for bg in common_keys)
+        total_weight = sum(bigrams1.values()) + sum(bigrams2.values())
+
+        dice_score = (2.0 * common_weight) / total_weight if total_weight > 0 else 0.0
+        h7 = 1 if dice_score >= self.freq_dice_threshold else 0
+
+        # H4: ペア評価では常に0（クラスタ分析時のみ昇格）
+        h4 = 0
+
+        v0_mask = f"{h1}{h2}{h3}{h4}"
+        ext_mask = f"{h5}{h6}{h7}"
+
+        return {
+            "h_states": {"H1": h1, "H2": h2, "H3": h3, "H4": h4, "H5": h5, "H6": h6, "H7": h7},
+            "v0_mask": v0_mask,
+            "mask": f"{v0_mask}-{ext_mask}",
+            "short_circuited": False,
+            "scores": {
+                "h3_score": h3_score,
+                "h7_dice_score": dice_score,
+            },
+        }
+
+    @staticmethod
+    def _get_weighted_bigrams(identifiers: List[str]) -> Dict[str, float]:
+        """識別子列から Bi-gram と出現頻度（重み）を生成"""
+        bigrams = defaultdict(float)
+        for i in range(len(identifiers) - 1):
+            bg = f"{identifiers[i]}___{identifiers[i+1]}"
+            bigrams[bg] += 1.0
+        return bigrams
+
+
+def _pair_worker_func(args):
+    """ProcessPoolExecutor用のトップレベル並列ワーカー関数"""
+    key1, code1, key2, code2, jaccard_th, freq_th = args
+    engine = SieveScopeEngineV1_3(jaccard_threshold=jaccard_th, freq_dice_threshold=freq_th)
+    result = engine.evaluate_pair(code1, code2)
+    return (key1, key2), result
+
+
+class SieveClusterAnalyzerV1_3:
+    """クラスタ解析・安全不変式・並列処理・間接伝搬警告エンジン"""
+
+    def __init__(self, engine: SieveScopeEngineV1_3, min_cluster_size: int = 3):
+        self.engine = engine
+        self.min_cluster_size = min_cluster_size
+
+    def analyze_corpus(self, corpus: Dict[str, str], max_workers: Optional[int] = None) -> Dict[str, Any]:
+        keys = sorted(list(corpus.keys()))
+        pair_tasks = []
+
+        for i in range(len(keys)):
+            for j in range(i + 1, len(keys)):
+                k1, k2 = keys[i], keys[j]
+                pair_tasks.append((
+                    k1, corpus[k1], k2, corpus[k2],
+                    self.engine.jaccard_threshold,
+                    self.engine.freq_dice_threshold,
+                ))
+
+        raw_pair_results = {}
+
+        if len(pair_tasks) > 10 and max_workers != 1:
+            with ProcessPoolExecutor(max_workers=max_workers) as executor:
+                futures = [executor.submit(_pair_worker_func, task) for task in pair_tasks]
+                for future in as_completed(futures):
+                    pair_key, res = future.result()
+                    raw_pair_results[pair_key] = res
+        else:
+            for task in pair_tasks:
+                pair_key, res = _pair_worker_func(task)
+                raw_pair_results[pair_key] = res
+
+        # 決定論的順序の保証
+        pair_results = dict(sorted(raw_pair_results.items()))
+
+        # 直接類似エッジの構築（H2=1 または H3=1）
+        direct_adj = defaultdict(set)
+        for (k1, k2), res in pair_results.items():
+            if res["h_states"]["H2"] == 1 or res["h_states"]["H3"] == 1:
+                direct_adj[k1].add(k2)
+                direct_adj[k2].add(k1)
+
+        # 連結成分抽出
+        visited = set()
+        valid_clusters = []
+        all_clusters = []
+
+        for node in keys:
+            if node not in visited:
+                component = set()
+                queue = deque([node])
+                visited.add(node)
+                while queue:
+                    curr = queue.popleft()
+                    component.add(curr)
+                    for neighbor in sorted(list(direct_adj[curr])):
+                        if neighbor not in visited:
+                            visited.add(neighbor)
+                            queue.append(neighbor)
+
+                all_clusters.append(component)
+                if len(component) >= self.min_cluster_size:
+                    valid_clusters.append(component)
+
+        # H4 安全不変式の適用（有効クラスタ内・直接類似のあるペアのみ昇格）
+        valid_nodes = set().union(*valid_clusters) if valid_clusters else set()
+
+        for (k1, k2), res in pair_results.items():
+            is_direct = (res["h_states"]["H2"] == 1 or res["h_states"]["H3"] == 1)
+            in_valid_cluster = (k1 in valid_nodes and k2 in valid_nodes and
+                                any(k1 in cl and k2 in cl for cl in valid_clusters))
+
+            if in_valid_cluster and is_direct:
+                res["h_states"]["H4"] = 1
+                h = res["h_states"]
+                res["v0_mask"] = f"{h['H1']}{h['H2']}{h['H3']}1"
+                res["mask"] = f"{res['v0_mask']}-{h['H5']}{h['H6']}{h['H7']}"
+
+        # 間接伝搬チェーン警告の検出
+        warnings = self.detect_indirect_chains(keys, direct_adj, valid_clusters)
+
+        return {
+            "valid_clusters": [sorted(list(c)) for c in valid_clusters],
+            "all_clusters": [sorted(list(c)) for c in all_clusters],
+            "pair_results": pair_results,
+            "warnings": warnings,
+        }
+
+    @staticmethod
+    def detect_indirect_chains(nodes, direct_adj, valid_clusters):
+        warnings = []
+        for cluster in valid_clusters:
+            cluster_nodes = sorted(list(cluster))
+            for i in range(len(cluster_nodes)):
+                for j in range(i + 1, len(cluster_nodes)):
+                    u, v = cluster_nodes[i], cluster_nodes[j]
+                    if v not in direct_adj[u]:
+                        queue = deque([[u]])
+                        visited = {u}
+                        found_path = None
+                        while queue:
+                            path = queue.popleft()
+                            curr = path[-1]
+                            if curr == v:
+                                found_path = path
+                                break
+                            for neighbor in sorted(list(direct_adj[curr])):
+                                if neighbor not in visited and neighbor in cluster:
+                                    visited.add(neighbor)
+                                    queue.append(path + [neighbor])
+                        if found_path and len(found_path) > 2:
+                            warnings.append({
+                                "code": "INDIRECT_PLAGIARISM_CHAIN_WARNING",
+                                "pair": (u, v),
+                                "message": (
+                                    f"Direct similarity not confirmed between '{u}' and '{v}', "
+                                    f"but indirect chain detected via {len(found_path)-1} hops."
+                                ),
+                                "propagation_path": " -> ".join(found_path),
+                                "hops": len(found_path) - 1,
+                            })
+        return warnings