Skip to content

armgit / LEANN

Public Imported from GitHub
0

[MLsys2026 Best Paper]: https://arxiv.org/abs/2506.08276. RAG on Everything with LEANN. Enjoy 97% storage savings while running a fast, accurate, and 100% private RAG application on your personal device.

fix(watch): byte-hash sync with build extension filter (#345) (#377)

Aakash Suresh773a47ff69e8
diff --git a/packages/leann-core/src/leann/cli.py b/packages/leann-core/src/leann/cli.py
index d565c73..5aa486c 100644
--- a/packages/leann-core/src/leann/cli.py
+++ b/packages/leann-core/src/leann/cli.py
@@ -28,7 +28,7 @@ from .settings import (
resolve_openai_api_key,
resolve_openai_base_url,
)
-from .sync import FileSynchronizer
+from .sync import DEFAULT_INDEX_EXTENSIONS, FileSynchronizer, parse_include_extensions
def _normalize_path(path: str) -> str:
@@ -1535,61 +1535,7 @@ Examples:
# Ensure extensions start with a dot
code_extensions = [ext if ext.startswith(".") else f".{ext}" for ext in code_extensions]
else:
- # Use default supported file types
- code_extensions = [
- # Original document types
- ".txt",
- ".md",
- ".docx",
- ".pptx",
- # Code files for Claude Code integration
- ".py",
- ".js",
- ".ts",
- ".jsx",
- ".tsx",
- ".java",
- ".cpp",
- ".c",
- ".h",
- ".hpp",
- ".cs",
- ".go",
- ".rs",
- ".rb",
- ".php",
- ".swift",
- ".kt",
- ".scala",
- ".r",
- ".sql",
- ".sh",
- ".bash",
- ".zsh",
- ".fish",
- ".ps1",
- ".bat",
- # Config and markup files
- ".json",
- ".yaml",
- ".yml",
- ".xml",
- ".toml",
- ".ini",
- ".cfg",
- ".conf",
- ".html",
- ".css",
- ".scss",
- ".less",
- ".vue",
- ".svelte",
- # Data science
- ".ipynb",
- ".R",
- ".py",
- ".jl",
- ]
+ code_extensions = list(DEFAULT_INDEX_EXTENSIONS)
# Process each directory
if directories:
@@ -1843,11 +1789,8 @@ Examples:
print(f"Loaded {len(documents)} documents, {len(all_texts)} chunks")
return all_texts
- def _parse_file_types(self, custom_file_types: Optional[str]) -> Optional[list[str]]:
- if not custom_file_types:
- return None
- extensions = [ext.strip() for ext in custom_file_types.split(",") if ext.strip()]
- return [ext if ext.startswith(".") else f".{ext}" for ext in extensions]
+ def _parse_file_types(self, custom_file_types: Optional[str]) -> list[str]:
+ return parse_include_extensions(custom_file_types)
def _sync_ignore_patterns(self, include_hidden: bool) -> Optional[list[str]]:
if include_hidden:
@@ -1923,38 +1866,58 @@ Examples:
config["query_prompt_template"] = args.query_prompt_template
return config
- def _resolve_sync_roots(self, docs_paths: list[str]) -> list[str]:
- roots: set[str] = set()
+ def _resolve_sync_scope(self, docs_paths: list[str]) -> tuple[list[str], list[str]]:
+ directories: list[str] = []
+ files: list[str] = []
for path in docs_paths:
path_obj = Path(path).resolve()
if path_obj.is_dir():
- roots.add(str(path_obj))
+ directories.append(str(path_obj))
elif path_obj.is_file():
- roots.add(str(path_obj.parent))
- return sorted(roots)
+ files.append(str(path_obj))
+ return sorted(directories), sorted(files)
+
+ def _resolve_sync_roots(self, docs_paths: list[str]) -> list[str]:
+ """Directory roots only (legacy). Prefer _resolve_sync_scope."""
+ directories, _files = self._resolve_sync_scope(docs_paths)
+ return directories
def _create_synchronizers(
self,
index_dir: Path,
- roots: list[str],
- include_extensions: Optional[list[str]] = None,
- ignore_patterns: Optional[list[str]] = None,
+ directories: list[str],
+ explicit_files: list[str],
+ include_extensions: list[str],
+ include_hidden: bool = False,
) -> list[FileSynchronizer]:
"""Create FileSynchronizers with snapshots stored in the index dir. Shared by build and watch."""
synchronizers: list[FileSynchronizer] = []
- for root in roots:
+ for root in directories:
tag = hashlib.sha256(root.encode()).hexdigest()[:12]
snapshot_path = str(index_dir / f"sync_{tag}.pickle")
try:
fs = FileSynchronizer(
root_dir=root,
- ignore_patterns=ignore_patterns,
include_extensions=include_extensions,
+ include_hidden=include_hidden,
snapshot_path=snapshot_path,
)
synchronizers.append(fs)
except Exception as exc:
print(f"Warning: Failed to init synchronizer for {root}: {exc}")
+ if explicit_files:
+ tag = hashlib.sha256("|".join(explicit_files).encode()).hexdigest()[:12]
+ snapshot_path = str(index_dir / f"sync_files_{tag}.pickle")
+ try:
+ fs = FileSynchronizer(
+ explicit_files=explicit_files,
+ include_extensions=include_extensions,
+ include_hidden=include_hidden,
+ snapshot_path=snapshot_path,
+ )
+ synchronizers.append(fs)
+ except Exception as exc:
+ print(f"Warning: Failed to init synchronizer for explicit files: {exc}")
return synchronizers
def _build_synchronizers(
@@ -1965,10 +1928,11 @@ Examples:
include_hidden: bool = False,
) -> list[FileSynchronizer]:
"""Create FileSynchronizers for build from docs_paths."""
- roots = self._resolve_sync_roots(docs_paths)
+ directories, files = self._resolve_sync_scope(docs_paths)
include_extensions = self._parse_file_types(file_types)
- ignore_patterns = self._sync_ignore_patterns(include_hidden)
- return self._create_synchronizers(index_dir, roots, include_extensions, ignore_patterns)
+ return self._create_synchronizers(
+ index_dir, directories, files, include_extensions, include_hidden
+ )
def _detect_build_changes(
self,
@@ -2243,33 +2207,62 @@ Examples:
def _write_sync_config(
self,
index_dir: Path,
- roots: list[str],
- include_extensions: Optional[list[str]],
- ignore_patterns: Optional[list[str]],
+ directories: list[str],
+ explicit_files: list[str],
+ include_extensions: list[str],
+ include_hidden: bool,
build_config: Optional[dict[str, Any]] = None,
) -> None:
sync_config_path = index_dir / "sync_roots.json"
config = {
- "roots": roots,
+ "directories": directories,
+ "files": explicit_files,
+ "roots": directories,
"include_extensions": include_extensions,
- "ignore_patterns": ignore_patterns,
+ "ignore_patterns": self._sync_ignore_patterns(include_hidden),
}
if build_config is not None:
config["build_config"] = build_config
with open(sync_config_path, "w", encoding="utf-8") as f:
json.dump(config, f, indent=2)
- def _load_sync_roots(self, index_dir: Path) -> list[str]:
- """Load sync roots from index dir (for path resolution in incremental updates)."""
+ def _write_sync_config_for_docs(
+ self,
+ index_dir: Path,
+ docs_paths: list[str],
+ args,
+ build_config: Optional[dict[str, Any]] = None,
+ ) -> None:
+ directories, files = self._resolve_sync_scope(docs_paths)
+ self._write_sync_config(
+ index_dir,
+ directories,
+ files,
+ self._parse_file_types(args.file_types),
+ args.include_hidden,
+ build_config,
+ )
+
+ def _load_sync_scope(self, index_dir: Path) -> tuple[list[str], list[str], list[str], bool]:
+ """Load sync scope from index dir (directories, files, extensions, include_hidden)."""
sync_config_path = index_dir / "sync_roots.json"
if not sync_config_path.exists():
- return []
+ return [], [], list(DEFAULT_INDEX_EXTENSIONS), False
try:
with open(sync_config_path, encoding="utf-8") as f:
config = json.load(f)
- return config.get("roots") or []
except (json.JSONDecodeError, OSError):
- return []
+ return [], [], list(DEFAULT_INDEX_EXTENSIONS), False
+ directories = config.get("directories") or config.get("roots") or []
+ files = config.get("files") or []
+ include_extensions = config.get("include_extensions") or list(DEFAULT_INDEX_EXTENSIONS)
+ include_hidden = config.get("ignore_patterns") is None
+ return directories, files, include_extensions, include_hidden
+
+ def _load_sync_roots(self, index_dir: Path) -> list[str]:
+ """Load directory + explicit file paths for chunk ID lookup."""
+ directories, files, _, _ = self._load_sync_scope(index_dir)
+ return directories + files
def _resolve_index_for_watch(self, index_name: str) -> Optional[dict[str, Path]]:
if self.index_exists(index_name):
@@ -2462,19 +2455,13 @@ Examples:
)
if result:
self._commit_synchronizers(synchronizers)
- self._write_sync_config(
- index_dir,
- self._resolve_sync_roots(docs_paths),
- self._parse_file_types(args.file_types),
- self._sync_ignore_patterns(args.include_hidden),
- build_config,
- )
+ self._write_sync_config_for_docs(index_dir, docs_paths, args, build_config)
self.register_project_dir()
return
- # Load only changed files (no need to load/chunk the entire corpus)
- # Resolve paths relative to sync roots (sync returns paths relative to each root)
- roots = self._resolve_sync_roots(docs_paths)
+ # Resolve paths relative to sync scope (directories + explicit files).
+ sync_dirs, sync_files = self._resolve_sync_scope(docs_paths)
+ scope_roots = sync_dirs + sync_files
paths_to_load = new_paths | modified_paths
resolved_paths: list[str] = []
for p in paths_to_load:
@@ -2482,7 +2469,7 @@ Examples:
if path_obj.is_absolute() and path_obj.exists():
resolved_paths.append(p)
else:
- for root in roots:
+ for root in scope_roots:
candidate = Path(root) / p
if candidate.exists():
resolved_paths.append(str(candidate.resolve()))
@@ -2509,17 +2496,11 @@ Examples:
new_paths,
removed_paths,
modified_paths,
- roots,
+ scope_roots,
)
if result:
self._commit_synchronizers(synchronizers)
- self._write_sync_config(
- index_dir,
- self._resolve_sync_roots(docs_paths),
- self._parse_file_types(args.file_types),
- self._sync_ignore_patterns(args.include_hidden),
- build_config,
- )
+ self._write_sync_config_for_docs(index_dir, docs_paths, args, build_config)
self.register_project_dir()
return
@@ -2532,13 +2513,7 @@ Examples:
)
if result:
self._commit_synchronizers(synchronizers)
- self._write_sync_config(
- index_dir,
- self._resolve_sync_roots(docs_paths),
- self._parse_file_types(args.file_types),
- self._sync_ignore_patterns(args.include_hidden),
- build_config,
- )
+ self._write_sync_config_for_docs(index_dir, docs_paths, args, build_config)
self.register_project_dir()
return
@@ -2594,13 +2569,7 @@ Examples:
)
for fs in target_synchronizers:
fs.create_snapshot()
- self._write_sync_config(
- target_index_dir,
- self._resolve_sync_roots(docs_paths),
- self._parse_file_types(args.file_types),
- self._sync_ignore_patterns(args.include_hidden),
- build_config,
- )
+ self._write_sync_config_for_docs(target_index_dir, docs_paths, args, build_config)
if publish_from_staging:
_publish_rebuilt_index(target_index_dir, index_dir)
except Exception:
@@ -2623,18 +2592,16 @@ Examples:
if not sync_config_path.exists():
return set(), set(), set()
- with open(sync_config_path, encoding="utf-8") as f:
- config = json.load(f)
-
- roots = config.get("roots") or []
- if not roots:
+ directories, files, include_extensions, include_hidden = self._load_sync_scope(index_dir)
+ if not directories and not files:
return set(), set(), set()
synchronizers = self._create_synchronizers(
index_dir,
- roots,
- include_extensions=config.get("include_extensions"),
- ignore_patterns=config.get("ignore_patterns"),
+ directories,
+ files,
+ include_extensions,
+ include_hidden,
)
return self._detect_build_changes(synchronizers)
diff --git a/packages/leann-core/src/leann/sync.py b/packages/leann-core/src/leann/sync.py
index ceca9b1..fa04bd1 100644
--- a/packages/leann-core/src/leann/sync.py
+++ b/packages/leann-core/src/leann/sync.py
@@ -3,12 +3,62 @@ import os
import pickle
from dataclasses import dataclass, field
from hashlib import sha256
+from pathlib import Path
from typing import Optional
-from llama_index.core import SimpleDirectoryReader
-
logger = logging.getLogger(__name__)
+# Keep in sync with leann build's default extension allowlist (load_documents).
+DEFAULT_INDEX_EXTENSIONS: list[str] = [
+ ".txt",
+ ".md",
+ ".docx",
+ ".pptx",
+ ".py",
+ ".js",
+ ".ts",
+ ".jsx",
+ ".tsx",
+ ".java",
+ ".cpp",
+ ".c",
+ ".h",
+ ".hpp",
+ ".cs",
+ ".go",
+ ".rs",
+ ".rb",
+ ".php",
+ ".swift",
+ ".kt",
+ ".scala",
+ ".r",
+ ".sql",
+ ".sh",
+ ".bash",
+ ".zsh",
+ ".fish",
+ ".ps1",
+ ".bat",
+ ".json",
+ ".yaml",
+ ".yml",
+ ".xml",
+ ".toml",
+ ".ini",
+ ".cfg",
+ ".conf",
+ ".html",
+ ".css",
+ ".scss",
+ ".less",
+ ".vue",
+ ".svelte",
+ ".ipynb",
+ ".R",
+ ".jl",
+]
+
def hash_data(data: str | bytes):
if isinstance(data, str):
@@ -16,6 +66,59 @@ def hash_data(data: str | bytes):
return sha256(data).hexdigest()
+def parse_include_extensions(custom_file_types: Optional[str]) -> list[str]:
+ """Return the extension allowlist used for sync/watch (matches build defaults)."""
+ if not custom_file_types:
+ return list(DEFAULT_INDEX_EXTENSIONS)
+ extensions = [ext.strip() for ext in custom_file_types.split(",") if ext.strip()]
+ return [ext if ext.startswith(".") else f".{ext}" for ext in extensions]
+
+
+def _extension_allowed(path: Path, include_extensions: list[str]) -> bool:
+ allowed = {ext.lower() for ext in include_extensions}
+ return path.suffix.lower() in allowed
+
+
+def _path_has_hidden_segment(path: Path) -> bool:
+ return any(part.startswith(".") and part not in (".", "..") for part in path.parts)
+
+
+def _hash_file_bytes(path: Path) -> str:
+ with open(path, "rb") as f:
+ return hash_data(f.read())
+
+
+def _iter_directory_files(
+ root_dir: str,
+ include_extensions: list[str],
+ include_hidden: bool,
+) -> list[str]:
+ root = Path(root_dir).resolve()
+ if not root.is_dir():
+ return []
+
+ paths: list[str] = []
+ for dirpath, dirnames, filenames in os.walk(root):
+ if not include_hidden:
+ dirnames[:] = [d for d in dirnames if not d.startswith(".")]
+ current = Path(dirpath)
+ for name in filenames:
+ if not include_hidden and name.startswith("."):
+ continue
+ file_path = (current / name).resolve()
+ try:
+ rel = file_path.relative_to(root)
+ except ValueError:
+ continue
+ if not include_hidden and _path_has_hidden_segment(rel):
+ continue
+ if not _extension_allowed(file_path, include_extensions):
+ continue
+ if file_path.is_file():
+ paths.append(str(file_path))
+ return paths
+
+
@dataclass
class MerkleTreeNode:
## TODO: this merkle tree only has two layer, need to improve if we want to scale to large codebase
@@ -74,53 +177,60 @@ class MerkleTree:
class FileSynchronizer:
def __init__(
self,
- root_dir: str,
+ root_dir: Optional[str] = None,
+ explicit_files: Optional[list[str]] = None,
ignore_patterns: Optional[list] = None,
- include_extensions: Optional[list] = None,
+ include_extensions: Optional[list[str]] = None,
+ include_hidden: bool = False,
auto_load=True,
snapshot_path: Optional[str] = None,
):
- if not os.path.isdir(root_dir):
+ self.root_dir = str(Path(root_dir).resolve()) if root_dir else None
+ self.explicit_files = (
+ [str(Path(path).resolve()) for path in explicit_files] if explicit_files else []
+ )
+ if self.root_dir is None and not self.explicit_files:
+ raise ValueError("FileSynchronizer requires root_dir and/or explicit_files")
+ if self.root_dir is not None and not os.path.isdir(self.root_dir):
raise ValueError("This is not a valid directory")
- self.root_dir = root_dir
+
self.ignore_patterns = ignore_patterns
- self.include_extensions = include_extensions
+ self.include_extensions = include_extensions or list(DEFAULT_INDEX_EXTENSIONS)
+ self.include_hidden = include_hidden
self._custom_snapshot_path = snapshot_path
self._pending_tree: Optional[MerkleTree] = None
self.tree: Optional[MerkleTree] = None
if auto_load:
self.load_snapshot()
- def generate_file_hashes(self):
- file_hashes = {}
- try:
- reader = SimpleDirectoryReader(
- self.root_dir,
- recursive=True,
- exclude=self.ignore_patterns,
- required_exts=self.include_extensions,
- exclude_empty=False,
+ def _collect_paths(self) -> list[str]:
+ paths: list[str] = []
+ if self.root_dir:
+ paths.extend(
+ _iter_directory_files(
+ self.root_dir,
+ self.include_extensions,
+ self.include_hidden,
+ )
)
- except ValueError:
- # Empty directory — no files to hash
- return file_hashes
-
- for file in reader.iter_data():
- if not file:
+ for file_path in self.explicit_files:
+ path = Path(file_path).resolve()
+ if not path.is_file():
continue
- file_path = file[0].metadata.get("file_path", "")
- if not file_path:
+ if not self.include_hidden and _path_has_hidden_segment(path):
continue
- try:
- # Combine text from all documents for this file (e.g. multi-page PDFs).
- # Previously we skipped len(file) > 1, which dropped every such file from
- # file_hashes — first build then saw "no changes" with an empty index (#290).
- combined_text = "".join(doc.text for doc in file)
- file_hashes[file_path] = hash_data(combined_text)
- except Exception:
- logger.error(f"Cannot hash file {file_path}")
+ if not _extension_allowed(path, self.include_extensions):
continue
+ paths.append(str(path))
+ return sorted(set(paths))
+ def generate_file_hashes(self):
+ file_hashes: dict[str, str] = {}
+ for file_path in self._collect_paths():
+ try:
+ file_hashes[file_path] = _hash_file_bytes(Path(file_path))
+ except OSError:
+ logger.warning("Cannot hash file %s", file_path)
return file_hashes
def build_merkle_tree(self, file_hashes):
@@ -173,7 +283,8 @@ class FileSynchronizer:
def snapshot_path(self):
if self._custom_snapshot_path:
return self._custom_snapshot_path
- return f"{self.root_dir}.sync_context.pickle"
+ base = self.root_dir or "files"
+ return f"{base}.sync_context.pickle"
def save_snapshot(self):
assert self.tree is not None
diff --git a/tests/test_sync.py b/tests/test_sync.py
index 57f9bcb..f57971a 100644
--- a/tests/test_sync.py
+++ b/tests/test_sync.py
@@ -1,7 +1,8 @@
import os
import tempfile
import unittest
-from unittest.mock import Mock, patch
+from pathlib import Path
+from unittest.mock import Mock
from leann.sync import FileSynchronizer, MerkleTree, hash_data
@@ -24,13 +25,11 @@ class TestMerkleTreeCompare(unittest.TestCase):
tree1 = Mock()
tree2 = Mock()
- # Mock file nodes
file_a_new = Mock()
file_b_new = Mock()
file_a_old = Mock()
file_c_old = Mock()
- # Equality behavior
file_a_new.__eq__ = Mock(return_value=False)
tree1.root = Mock(
@@ -58,50 +57,48 @@ class TestMerkleTreeCompare(unittest.TestCase):
class TestFileSynchronizer(unittest.TestCase):
def test_generate_file_hashes(self):
- temp_dir = tempfile.gettempdir()
- fs = FileSynchronizer(temp_dir, auto_load=False)
-
- mock_file = Mock()
- mock_file.text = "hello world"
- mock_file.metadata = {"file_path": os.path.join(temp_dir, "file.txt")}
-
- mock_reader_instance = Mock()
- mock_reader_instance.iter_data.return_value = [
- [mock_file],
- ]
-
- with patch("leann.sync.SimpleDirectoryReader") as mock_reader:
- mock_reader.return_value = mock_reader_instance
-
+ with tempfile.TemporaryDirectory() as temp_dir:
+ file_path = Path(temp_dir) / "file.txt"
+ file_path.write_text("hello world", encoding="utf-8")
+ fs = FileSynchronizer(root_dir=temp_dir, auto_load=False)
result = fs.generate_file_hashes()
-
- assert result == {os.path.join(temp_dir, "file.txt"): hash_data("hello world")}
-
- def test_generate_file_hashes_multi_document_same_path(self):
- """Multi-page PDFs etc. yield multiple docs per path; combine text for hashing (#290)."""
- temp_dir = tempfile.gettempdir()
- path = os.path.join(temp_dir, "doc.pdf")
- fs = FileSynchronizer(temp_dir, auto_load=False)
-
- p1 = Mock()
- p1.text = "aa"
- p1.metadata = {"file_path": path}
- p2 = Mock()
- p2.text = "bb"
- p2.metadata = {"file_path": path}
-
- mock_reader_instance = Mock()
- mock_reader_instance.iter_data.return_value = [[p1, p2]]
-
- with patch("leann.sync.SimpleDirectoryReader") as mock_reader:
- mock_reader.return_value = mock_reader_instance
-
+ assert result == {str(file_path.resolve()): hash_data(file_path.read_bytes())}
+
+ def test_generate_file_hashes_skips_binary_extensions(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ root = Path(temp_dir)
+ (root / "code.py").write_text("print('hi')", encoding="utf-8")
+ (root / "image.png").write_bytes(b"\x89PNG\r\n")
+ fs = FileSynchronizer(
+ root_dir=temp_dir,
+ include_extensions=[".py"],
+ auto_load=False,
+ )
result = fs.generate_file_hashes()
-
- assert result == {path: hash_data("aabb")}
+ assert len(result) == 1
+ assert str((root / "code.py").resolve()) in result
+
+ def test_generate_file_hashes_explicit_files_only(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ root = Path(temp_dir)
+ src = root / "src"
+ src.mkdir()
+ readme = root / "README.md"
+ readme.write_text("# hi", encoding="utf-8")
+ (src / "module.py").write_text("x = 1", encoding="utf-8")
+ (root / "assets").mkdir()
+ (root / "assets" / "icon.png").write_bytes(b"png")
+
+ fs = FileSynchronizer(
+ explicit_files=[str(readme.resolve())],
+ include_extensions=[".md"],
+ auto_load=False,
+ )
+ result = fs.generate_file_hashes()
+ assert set(result.keys()) == {str(readme.resolve())}
def test_build_merkle_tree(self):
- fs = FileSynchronizer(".", auto_load=False)
+ fs = FileSynchronizer.__new__(FileSynchronizer)
file_hashes = {
"a.txt": "hashA",
@@ -110,13 +107,8 @@ class TestFileSynchronizer(unittest.TestCase):
tree = fs.build_merkle_tree(file_hashes)
- # Root exists
assert tree.root is not None
-
- # Children added correctly
assert set(tree.root.children.keys()) == {"a.txt", "b.txt"}
-
- # Child nodes have correct data
assert tree.root.children["a.txt"].data == "hashA"
assert tree.root.children["b.txt"].data == "hashB"
@@ -146,3 +138,18 @@ class TestFileSynchronizer(unittest.TestCase):
fs.save_snapshot.assert_called_once()
assert fs.tree is new_tree
+
+ def test_touch_no_false_positive(self):
+ with tempfile.TemporaryDirectory() as temp_dir:
+ docs = Path(temp_dir)
+ f = docs / "a.txt"
+ f.write_text("hello", encoding="utf-8")
+ snapshot = str(docs / "test.pickle")
+ fs = FileSynchronizer(root_dir=str(docs), snapshot_path=snapshot)
+ fs.detect_changes()
+ fs.commit()
+
+ os.utime(f, None)
+ fs2 = FileSynchronizer(root_dir=str(docs), snapshot_path=snapshot)
+ added, removed, modified = fs2.detect_changes()
+ assert not added and not removed and not modified
diff --git a/tests/test_watch_sync_scope.py b/tests/test_watch_sync_scope.py
new file mode 100644
index 0000000..7c30602
--- /dev/null
+++ b/tests/test_watch_sync_scope.py
@@ -0,0 +1,83 @@
+"""Regression tests for leann watch sync scope (#345)."""
+
+from leann.cli import LeannCLI
+from leann.sync import FileSynchronizer
+
+
+def test_resolve_sync_scope_keeps_loose_files_separate(tmp_path):
+ repo = tmp_path / "repo"
+ src = repo / "src"
+ src.mkdir(parents=True)
+ readme = repo / "README.md"
+ readme.write_text("# hello", encoding="utf-8")
+
+ cli = LeannCLI()
+ directories, files = cli._resolve_sync_scope([str(src), str(readme)])
+
+ assert directories == [str(src.resolve())]
+ assert files == [str(readme.resolve())]
+
+
+def test_watch_scope_does_not_scan_sibling_media(tmp_path):
+ repo = tmp_path / "repo"
+ src = repo / "src"
+ assets = repo / "assets"
+ src.mkdir(parents=True)
+ assets.mkdir()
+ readme = repo / "README.md"
+ readme.write_text("# hello", encoding="utf-8")
+ (src / "main.py").write_text("print('ok')", encoding="utf-8")
+ (assets / "icon.png").write_bytes(b"png")
+
+ synchronizers = [
+ FileSynchronizer(
+ root_dir=str(src),
+ include_extensions=[".py", ".md"],
+ snapshot_path=str(tmp_path / "sync_src.pickle"),
+ auto_load=False,
+ ),
+ FileSynchronizer(
+ explicit_files=[str(readme.resolve())],
+ include_extensions=[".py", ".md"],
+ snapshot_path=str(tmp_path / "sync_readme.pickle"),
+ auto_load=False,
+ ),
+ ]
+
+ hashed_paths: set[str] = set()
+ for fs in synchronizers:
+ hashed_paths.update(fs.generate_file_hashes().keys())
+
+ assert str((src / "main.py").resolve()) in hashed_paths
+ assert str(readme.resolve()) in hashed_paths
+ assert str((assets / "icon.png").resolve()) not in hashed_paths
+
+
+def test_mixed_txt_and_bin_directory_skips_bin_without_crash(tmp_path):
+ """Same dir with .txt and .bin: hash only text, ignore binary (review #377)."""
+ docs = tmp_path / "docs"
+ docs.mkdir()
+ txt = docs / "notes.txt"
+ bin_file = docs / "payload.bin"
+ txt.write_text("hello", encoding="utf-8")
+ bin_file.write_bytes(bytes(range(256)))
+
+ fs = FileSynchronizer(
+ root_dir=str(docs),
+ include_extensions=[".txt"],
+ snapshot_path=str(tmp_path / "sync.pickle"),
+ auto_load=False,
+ )
+
+ hashes = fs.generate_file_hashes()
+ assert set(hashes.keys()) == {str(txt.resolve())}
+ assert str(bin_file.resolve()) not in hashes
+
+ fs.create_snapshot()
+ fs2 = FileSynchronizer(
+ root_dir=str(docs),
+ include_extensions=[".txt"],
+ snapshot_path=str(tmp_path / "sync.pickle"),
+ )
+ added, removed, modified = fs2.detect_changes()
+ assert not added and not removed and not modified