Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(watch): index the working tree, so epowise watch actually updates (#1363)

Raghav Chamadiya2af44328e123
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 11a6083a0..32a9a82ab 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -373,6 +373,14 @@ Pass `--refresh-ui` to skip (1) and (2) and force (3).
Watch for file changes and auto-update wiki pages. Press `Ctrl+C` to stop.
+Unlike the post-commit hook, this indexes **uncommitted** work: staged,
+unstaged and untracked files all reach the index, so what you see in the wiki
+matches what is on disk rather than what you last committed.
+
+Writes inside `.repowise/`, `.git/`, `node_modules/`, build output and the
+files repowise manages itself (`CLAUDE.md`, `AGENTS.md`, `.mcp.json`) never
+trigger an update.
+
**Options:**
| Flag | Description |
@@ -382,17 +390,21 @@ Watch for file changes and auto-update wiki pages. Press `Ctrl+C` to stop.
| `--debounce` | Delay in ms after last change (default: 2000) |
| `--workspace` / `-w` | Watch all workspace repos |
| `--no-workspace` | Force single-repo mode |
-| `--repo` | Watch a single workspace repo by alias |
+| `--index-only` | Skip LLM page regeneration on every trigger (workspace mode is index-only either way) |
| `--verbose` / `-v` | Show debug logs from the pipeline and triggered updates |
```bash
repowise watch # single repo (auto-detects)
repowise watch --debounce 5000 # 5s debounce
repowise watch --workspace # all workspace repos
-repowise watch --repo backend # just one
+repowise watch --index-only # no model calls per save
repowise watch --verbose # show pipeline debug logs
```
+On a repo indexed with docs, every trigger is a page regeneration with a model
+behind it. `--index-only` keeps the index, graph and health current for free
+and leaves the prose to a later `repowise update`.
+
---
## Query Commands
diff --git a/docs/scale/AUTO_SYNC.md b/docs/scale/AUTO_SYNC.md
index 0a79208b5..6c01ade7b 100644
--- a/docs/scale/AUTO_SYNC.md
+++ b/docs/scale/AUTO_SYNC.md
@@ -64,14 +64,25 @@ Watches your working directory for file saves and auto-updates. Useful during
active development when you want the wiki to stay current without committing.
```bash
-repowise watch # watch current directory
+repowise watch # watch current directory
repowise watch /path/to/repo
repowise watch --debounce 5000 # wait 5s after last change (default: 2s)
+repowise watch --index-only # no model calls per save
```
Press `Ctrl+C` to stop.
-Changes to files inside `.repowise/` are ignored to prevent update loops.
+Unlike the post-commit hook, the watcher indexes the working tree: staged,
+unstaged and untracked files all reach the index without a commit.
+
+Ignored, so a build or an update of repowise's own files never triggers a run:
+`.repowise/`, `.git/`, `node_modules/`, build output and other blocklisted
+directories, lockfiles and non-source files, and the files repowise manages
+itself (`CLAUDE.md`, `AGENTS.md`, `.mcp.json`, `.claude/`).
+
+On a repo indexed with docs, each trigger regenerates the changed files' pages
+with a model. Use `--index-only` to keep the index current for free and leave
+the prose for a later `repowise update`.
---
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 964f56468..f75c237ef 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -119,7 +119,7 @@ repowise update --since a1b2c3d
### `repowise watch`
-Watch a repository for file changes and automatically run `repowise update` after a debounce period. Useful during active development.
+Watch a repository for file changes and automatically run `repowise update` after a debounce period. Useful during active development: it indexes the working tree, so staged, unstaged and untracked files reach the index without a commit.
```
repowise watch [PATH] [OPTIONS]
@@ -130,6 +130,7 @@ repowise watch [PATH] [OPTIONS]
| `--provider` | last used | LLM provider |
| `--model` | provider default | Model override |
| `--debounce` | `2000` | Milliseconds to wait after the last change before updating |
+| `--index-only` | off | Skip LLM page regeneration on every trigger |
```bash
# Watch current directory
@@ -137,9 +138,12 @@ repowise watch
# Custom debounce (wait 5 seconds after last change)
repowise watch --debounce 5000
+
+# Keep the index current without a model call per save
+repowise watch --index-only
```
-Press `Ctrl+C` to stop. Changes to `.repowise/` are automatically ignored.
+Press `Ctrl+C` to stop. Writes to `.repowise/`, `.git/`, build output, and the files repowise manages itself (`CLAUDE.md`, `AGENTS.md`, `.mcp.json`) never trigger an update.
---
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 18b1a6e28..72fac8def 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -538,6 +538,7 @@ def run_update(
verbose: bool = False,
progress: str = "rich",
skip_cross_repo_hooks: bool = False,
+ include_working_tree: bool = False,
) -> UpdateOutcome:
"""Incrementally update wiki pages for files changed since last sync.
@@ -546,6 +547,14 @@ def run_update(
``skip_cross_repo_hooks`` is set only by the workspace docs flow, which
calls this per repo and then runs the cross-repo hooks once over every
updated repo instead of once per repo.
+
+ ``include_working_tree`` folds uncommitted work (staged, unstaged and
+ untracked) into the change set on top of the commit range. Off by default,
+ because every other caller is anchored to a commit — the post-commit hook,
+ a webhook, a manual sync — and indexing a half-finished edit under those is
+ not what the user asked for. ``repowise watch`` sets it: watching for file
+ saves and then only ever diffing commit-to-commit is what made the watcher
+ a no-op until you committed.
"""
start = time.monotonic()
@@ -747,7 +756,39 @@ def run_update(
curr_renderer_fp = _current_renderer_fingerprint(repo_path)
renderer_changed = prev_renderer_fp is not None and prev_renderer_fp != curr_renderer_fp
- if head and head == base_ref and not config_changed and not renderer_changed:
+ # Uncommitted work, when the caller asked for it. Computed before the
+ # "already up to date" gate below, because on a watched repo that gate is
+ # exactly what the change set has to get past: with no new commits,
+ # ``head == base_ref`` is the normal state, not an idle one.
+ from repowise.core.ingestion import ChangeDetector
+
+ detector = ChangeDetector(repo_path)
+ working_tree_diffs: list = []
+ if include_working_tree:
+ working_tree_diffs = detector.get_working_tree_changes()
+ dirty_paths = {fd.path for fd in working_tree_diffs}
+ # Work the last working-tree run indexed that is no longer diverging
+ # from HEAD: a reverted edit, or a deleted file that was only ever
+ # untracked. Nothing else would ever mention those paths again, so
+ # without this the index keeps serving content that is gone.
+ working_tree_diffs += detector.stale_working_tree_diffs(
+ state.get("working_tree_paths") or [], dirty_paths
+ )
+ # Carried on ``state`` from here so every save_state below persists it,
+ # including the early-return paths.
+ state["working_tree_paths"] = sorted(dirty_paths)
+ if working_tree_diffs:
+ console.print(
+ f"[dim]Uncommitted changes: [bold]{len(working_tree_diffs)}[/bold] file(s)[/dim]"
+ )
+
+ if (
+ head
+ and head == base_ref
+ and not config_changed
+ and not renderer_changed
+ and not working_tree_diffs
+ ):
console.print("[green]Already up to date.[/green]")
# D7: on a template (index-only) wiki, "up to date" is true of the code
# but the pages are still unwritten. Point at the command that writes
@@ -941,10 +982,12 @@ def run_update(
if emitter is not None:
emitter.stage("detect_changes")
- from repowise.core.ingestion import ChangeDetector
+ from repowise.core.ingestion.change_detector import merge_file_diffs
- detector = ChangeDetector(repo_path)
- file_diffs = detector.get_changed_files(base_ref, head or "HEAD")
+ file_diffs = merge_file_diffs(
+ detector.get_changed_files(base_ref, head or "HEAD"),
+ working_tree_diffs,
+ )
if not file_diffs and not config_changed and not renderer_changed:
console.print("[green]No changed files detected.[/green]")
diff --git a/packages/cli/src/repowise/cli/commands/watch_cmd.py b/packages/cli/src/repowise/cli/commands/watch_cmd.py
index a4ca922b3..67a918812 100644
--- a/packages/cli/src/repowise/cli/commands/watch_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/watch_cmd.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import os
import threading
import time
from collections.abc import Callable
@@ -16,6 +17,88 @@ from repowise.cli.helpers import (
resolve_command_target,
run_async,
)
+from repowise.core.ingestion import is_candidate_source_path
+
+# ---------------------------------------------------------------------------
+# Which filesystem events are worth an update
+# ---------------------------------------------------------------------------
+
+#: Repo-root files repowise itself rewrites at the end of every update. An
+#: update that re-stamps CLAUDE.md would otherwise wake the watcher that
+#: started it, and — now that the watcher indexes uncommitted work — the two
+#: would drive each other in a loop for as long as `watch` is left running.
+_SELF_WRITTEN_FILES: frozenset[str] = frozenset({"CLAUDE.md", "AGENTS.md", ".mcp.json"})
+
+#: Same, for the per-agent config directories the editor setup manages.
+#: ``.repowise``, ``.git`` and ``.vscode`` need no entry — they are already
+#: blocked by the traversal blocklist :func:`is_candidate_source_path` reads.
+_SELF_WRITTEN_DIRS: frozenset[str] = frozenset({".claude", ".codex", ".cursor", ".gemini"})
+
+
+def _event_paths(event: object, repo_path: Path) -> set[str]:
+ """The watchable repo-relative paths a filesystem event touched.
+
+ Both ends of a move are considered. Editors that save atomically (the
+ JetBrains IDEs, Vim with ``backupcopy=no``, plenty of Windows tools) write
+ a temp file and rename it over the target, which arrives as one move event
+ whose ``src_path`` is the temp name — looking only there means the save
+ that matters is filtered out as junk and never wakes an update.
+
+ Paths outside the watched root are dropped rather than raising: an
+ unguarded ``relative_to`` here used to take watchdog's dispatcher thread
+ down with it, leaving ``watch`` apparently running but permanently deaf.
+ """
+ found: set[str] = set()
+ for attr in ("src_path", "dest_path"):
+ raw = getattr(event, attr, None)
+ if not raw:
+ continue
+ try:
+ rel = str(Path(raw).relative_to(repo_path))
+ except ValueError:
+ continue
+ if is_watchable_path(rel):
+ found.add(rel)
+ return found
+
+
+def _release_own_update_lock(repo_path: Path) -> None:
+ """Drop the repo's single-flight update lock if this process owns it.
+
+ ``run_update`` takes that lock and only gives it back through ``atexit``,
+ which is correct for the one-shot CLI runs every other caller makes and
+ wrong for a watcher: the process outlives the update, so the *next* save
+ finds a lock whose PID is alive (its own), reports "another update is
+ already running", and defers. Every save after the first would be a no-op
+ for the rest of the session.
+
+ Ownership is checked rather than assumed, so a lock a genuinely concurrent
+ ``repowise update`` holds is never deleted out from under it.
+ """
+ from repowise.core.update_lock import read_update_lock, release_update_lock
+
+ payload = read_update_lock(repo_path)
+ if payload is not None and payload.get("pid") == os.getpid():
+ release_update_lock(repo_path)
+
+
+def is_watchable_path(rel_path: str) -> bool:
+ """Whether a change to *rel_path* (repo-relative) should trigger an update.
+
+ Two filters. The first is the traversal blocklist, so a write inside
+ ``node_modules/``, ``.git/`` or ``dist/`` — or to a lockfile, a compiled
+ artifact, anything the index would not read — never wakes an update; a
+ single ``npm install`` otherwise means thousands of triggers. The second is
+ the set of files repowise writes itself, which would make the watcher
+ self-perpetuating.
+ """
+ posix = rel_path.replace("\\", "/")
+ if posix in _SELF_WRITTEN_FILES:
+ return False
+ if posix.split("/", 1)[0] in _SELF_WRITTEN_DIRS:
+ return False
+ return is_candidate_source_path(posix)
+
# ---------------------------------------------------------------------------
# Single-repo watch (existing behavior)
@@ -28,58 +111,71 @@ def _watch_single_repo(
model: str | None,
debounce_ms: int,
verbose: bool,
+ index_only: bool = False,
) -> None:
"""Watch a single repo for changes and trigger updates."""
from watchdog.events import FileSystemEventHandler
from watchdog.observers import Observer
+ from repowise.cli.commands.update_cmd.command import run_update
+
ensure_repowise_dir(repo_path)
changed_paths: set[str] = set()
lock = threading.Lock()
+ # Serialises the updates themselves. The debounce timer only guarantees a
+ # quiet gap before a run starts, not that the previous run has finished —
+ # an update that outlives the next quiet gap would otherwise have a second
+ # one started on top of it.
+ update_lock = threading.Lock()
timer: threading.Timer | None = None
def _on_trigger() -> None:
nonlocal timer
- with lock:
- paths = set(changed_paths)
- changed_paths.clear()
- timer = None
+ with update_lock:
+ with lock:
+ paths = set(changed_paths)
+ changed_paths.clear()
+ timer = None
- if not paths:
- return
+ if not paths:
+ return
- console.print(f"[cyan]Detected {len(paths)} changed file(s), updating...[/cyan]")
- try:
- from click.testing import CliRunner
-
- from repowise.cli.commands.update_cmd import update_command
-
- runner = CliRunner()
- args = [str(repo_path)]
- if provider_name:
- args.extend(["--provider", provider_name])
- if model:
- args.extend(["--model", model])
- if verbose:
- args.append("--verbose")
- result = runner.invoke(update_command, args, catch_exceptions=False)
- if result.output:
- console.print(result.output)
- except Exception as e:
- console.print(f"[red]Update failed: {e}[/red]")
+ console.print(f"[cyan]Detected {len(paths)} changed file(s), updating...[/cyan]")
+ try:
+ run_update(
+ path=str(repo_path),
+ provider_name=provider_name,
+ model=model,
+ since=None,
+ reasoning=None,
+ cascade_budget=None,
+ dry_run=False,
+ workspace=False,
+ no_workspace=True,
+ repo_alias=None,
+ index_only=index_only,
+ verbose=verbose,
+ # The whole point of a file watcher: the edits it saw are
+ # in the working tree, and nothing has been committed.
+ include_working_tree=True,
+ )
+ except Exception as e:
+ console.print(f"[red]Update failed: {e}[/red]")
+ finally:
+ _release_own_update_lock(repo_path)
class RepowiseHandler(FileSystemEventHandler):
def on_any_event(self, event):
nonlocal timer
if event.is_directory:
return
- rel = str(Path(event.src_path).relative_to(repo_path))
- if rel.startswith(".repowise"):
+ watched = _event_paths(event, repo_path)
+ if not watched:
return
with lock:
- changed_paths.add(rel)
+ changed_paths.update(watched)
if timer is not None:
timer.cancel()
timer = threading.Timer(debounce_ms / 1000.0, _on_trigger)
@@ -126,47 +222,55 @@ def _watch_workspace(
repo_locks: dict[str, threading.Lock] = {}
repo_changed: dict[str, set[str]] = {}
repo_timers: dict[str, threading.Timer | None] = {}
+ # Serialises a repo's own updates; see the single-repo watcher.
+ repo_update_locks: dict[str, threading.Lock] = {}
for entry in ws_config.repos:
repo_locks[entry.alias] = threading.Lock()
repo_changed[entry.alias] = set()
repo_timers[entry.alias] = None
+ repo_update_locks[entry.alias] = threading.Lock()
def _make_trigger(alias: str) -> Callable[[], None]:
"""Create a trigger function for a specific repo."""
def _on_trigger() -> None:
- with repo_locks[alias]:
- paths = set(repo_changed[alias])
- repo_changed[alias].clear()
- repo_timers[alias] = None
-
- if not paths:
- return
-
- console.print(f"[cyan]{alias}: {len(paths)} changed file(s), updating...[/cyan]")
- try:
- # Reload config in case it was updated
- current_config = WorkspaceConfig.load(ws_root)
- results = run_async(
- update_workspace(
- ws_root,
- current_config,
- repo_filter=alias,
- )
- )
- for r in results:
- if r.error:
- console.print(f" [red]{alias}: {r.error}[/red]")
- elif r.updated:
- console.print(
- f" [green]\u2713[/green] {alias}: "
- f"{r.file_count} files, {r.symbol_count:,} symbols"
+ with repo_update_locks[alias]:
+ with repo_locks[alias]:
+ paths = set(repo_changed[alias])
+ repo_changed[alias].clear()
+ repo_timers[alias] = None
+
+ if not paths:
+ return
+
+ console.print(f"[cyan]{alias}: {len(paths)} changed file(s), updating...[/cyan]")
+ try:
+ # Reload config in case it was updated
+ current_config = WorkspaceConfig.load(ws_root)
+ results = run_async(
+ update_workspace(
+ ws_root,
+ current_config,
+ repo_filter=alias,
+ # Same reason as the single-repo watcher: what the
+ # watcher saw is uncommitted, and the staleness
+ # check is otherwise commit-to-commit only.
+ include_working_tree=True,
)
- elif r.skipped_reason == "up_to_date":
- console.print(f" [dim]{alias}: already up to date[/dim]")
- except Exception as e:
- console.print(f" [red]{alias} update failed: {e}[/red]")
+ )
+ for r in results:
+ if r.error:
+ console.print(f" [red]{alias}: {r.error}[/red]")
+ elif r.updated:
+ console.print(
+ f" [green]\u2713[/green] {alias}: "
+ f"{r.file_count} files, {r.symbol_count:,} symbols"
+ )
+ elif r.skipped_reason == "up_to_date":
+ console.print(f" [dim]{alias}: already up to date[/dim]")
+ except Exception as e:
+ console.print(f" [red]{alias} update failed: {e}[/red]")
return _on_trigger
@@ -181,16 +285,13 @@ def _watch_workspace(
def on_any_event(self, event):
if event.is_directory:
return
- try:
- rel = str(Path(event.src_path).relative_to(self._repo_path))
- except ValueError:
- return
- if rel.startswith(".repowise"):
+ watched = _event_paths(event, self._repo_path)
+ if not watched:
return
alias = self._alias
with repo_locks[alias]:
- repo_changed[alias].add(rel)
+ repo_changed[alias].update(watched)
old_timer = repo_timers[alias]
if old_timer is not None:
old_timer.cancel()
@@ -256,6 +357,17 @@ def _watch_workspace(
default=False,
help="Force single-repo mode even when invoked from a workspace.",
)
+ "--index-only",
+ is_flag=True,
+ default=False,
+ help=(
+ "Skip LLM page regeneration on every trigger. A watched repo fires an "
+ "update per save, so on a repo indexed with docs that is a model call "
+ "per save; this keeps the index, graph and health current for free. "
+ "Workspace mode is index-only either way."
+ ),
+)
@click.option(
"--verbose",
"-v",
@@ -270,10 +382,14 @@ def watch_command(
debounce_ms: int,
workspace: bool,
no_workspace: bool,
+ index_only: bool,
verbose: bool,
) -> None:
"""Watch for file changes and auto-update wiki pages.
+ Picks up uncommitted work: staged, unstaged and untracked files all reach
+ the index, which is the difference between this and the post-commit hook.
+
Auto-detects workspace mode when invoked from a workspace root.
"""
configure_cli_logging(verbose=verbose)
@@ -296,4 +412,5 @@ def watch_command(
model,
debounce_ms,
verbose,
+ index_only,
)
diff --git a/packages/core/src/repowise/core/ingestion/__init__.py b/packages/core/src/repowise/core/ingestion/__init__.py
index 4a689d2b1..08321f951 100644
--- a/packages/core/src/repowise/core/ingestion/__init__.py
+++ b/packages/core/src/repowise/core/ingestion/__init__.py
@@ -28,7 +28,7 @@ from .models import (
compute_content_hash,
)
from .parser import LANGUAGE_CONFIGS, ASTParser, LanguageConfig, parse_file
-from .traverser import FileTraverser, TraversalStats
+from .traverser import FileTraverser, TraversalStats, is_candidate_source_path
from .tsconfig_resolver import TsconfigResolver, wire_tsconfig_resolver
__all__ = [
@@ -62,6 +62,7 @@ __all__ = [
"TraversalStats",
"TsconfigResolver",
"compute_content_hash",
+ "is_candidate_source_path",
"parse_file",
"wire_tsconfig_resolver",
]
diff --git a/packages/core/src/repowise/core/ingestion/change_detector.py b/packages/core/src/repowise/core/ingestion/change_detector.py
index 060a0411c..81b051b49 100644
--- a/packages/core/src/repowise/core/ingestion/change_detector.py
+++ b/packages/core/src/repowise/core/ingestion/change_detector.py
@@ -15,6 +15,7 @@ Key design decisions:
from __future__ import annotations
import difflib
+from collections.abc import Iterable
from dataclasses import dataclass, field
from pathlib import Path
from typing import Literal
@@ -22,6 +23,7 @@ from typing import Literal
import structlog
from .models import FileInfo, ParsedFile, Symbol
+from .traverser import is_candidate_source_path
log = structlog.get_logger(__name__)
@@ -138,65 +140,182 @@ class ChangeDetector:
log.warning("git diff failed", base=base_ref, until=until_ref, error=str(exc))
return []
+ return [self._file_diff_from_item(item) for item in diff_items]
+
+ def get_working_tree_changes(self) -> list[FileDiff]:
+ """Return FileDiffs for changes that are in the working tree, not in git.
+
+ Everything ``git status`` would show: staged and unstaged edits to
+ tracked files (diffed against ``HEAD``) plus untracked files, which git
+ reports as additions. Gitignored paths never appear — ``untracked_files``
+ applies the standard exclusions — and paths the index would skip anyway
+ (``.repowise/``, ``node_modules/``, lockfiles, non-source extensions)
+ are dropped here rather than travelling through the pipeline as no-op
+ page work. Unlike :meth:`get_changed_files`, which is bounded by what a
+ commit touched, this sees the whole untracked tree, so the filter is
+ what stops one un-gitignored build directory from swamping every run.
+
+ This is what ``repowise watch`` needs and what :meth:`get_changed_files`
+ cannot give it: a commit-range diff of ``HEAD..HEAD`` is empty by
+ definition, so a repo with unsaved-to-git edits reads as "already up to
+ date" no matter how much has changed on disk.
+
+ Falls back to an empty list on a non-git directory or an unborn HEAD
+ (a repo with no commits yet), matching :meth:`get_changed_files`.
+ """
+ repo = self._get_repo()
+ if repo is None:
+ return []
+
results: list[FileDiff] = []
+ try:
+ head_commit = repo.head.commit
+ # ``None`` as the diff target means "the working tree", so this
+ # covers staged and unstaged changes in one pass.
+ for item in head_commit.diff(None):
+ path = (item.b_path or item.a_path or "").replace("\\", "/")
+ if not is_candidate_source_path(path):
+ continue
+ results.append(self._file_diff_from_item(item))
+ untracked = list(repo.untracked_files)
+ except Exception as exc:
+ log.warning("working tree diff failed", error=str(exc))
+ return []
+
+ for rel_path in untracked:
+ path = rel_path.replace("\\", "/")
+ if not is_candidate_source_path(path):
+ continue
+ abs_path = self.repo_path / path
+ if not abs_path.is_file():
+ continue
+ results.append(self._added_from_disk(path, abs_path))
+
+ return results
- for item in diff_items:
- status: Literal["added", "deleted", "modified", "renamed"]
- old_path: str | None = None
- new_path: str | None = None
-
- change_type = item.change_type
- if change_type == "A":
- status = "added"
- new_path = item.b_path
- elif change_type == "D":
- status = "deleted"
- old_path = item.a_path
- elif change_type == "R":
- status = "renamed"
- old_path = item.a_path
- new_path = item.b_path
+ def stale_working_tree_diffs(
+ self,
+ previous_paths: Iterable[str],
+ current_paths: set[str],
+ ) -> list[FileDiff]:
+ """Diffs that undo working-tree work the index still reflects.
+
+ Working-tree state has no equivalent of ``last_sync_commit``: a path
+ stops being reported the moment it stops differing from ``HEAD``, so
+ nothing would ever tell a later run that the index is still carrying
+ it. Undo an edit, or delete an untracked file the watcher indexed, and
+ that content would otherwise be served forever — a symbol whose file
+ no longer has it, or a page for a file that no longer exists.
+
+ *previous_paths* is what the last working-tree run indexed. Anything
+ in it that is no longer diverging is re-diffed here: as ``deleted``
+ when it is gone from disk, and as ``modified`` (re-read from disk,
+ i.e. back to the committed content) when it is still there.
+ """
+ stale: list[FileDiff] = []
+ for rel_path in previous_paths:
+ path = str(rel_path).replace("\\", "/")
+ if path in current_paths:
+ continue
+ abs_path = self.repo_path / path
+ if abs_path.is_file():
+ stale.append(self._added_from_disk(path, abs_path, status="modified"))
else:
- status = "modified"
- old_path = item.a_path
- new_path = item.b_path
-
- path = new_path or old_path or ""
-
- # Parse old version (from git blob)
- old_parsed = None
- if old_path and item.a_blob:
- old_parsed = self._parse_blob(item.a_blob, old_path)
-
- # Parse new version (from working tree)
- new_parsed = None
- if new_path:
- abs_path = self.repo_path / new_path
- if abs_path.exists():
- new_parsed = self._parse_path(abs_path, new_path)
- elif item.b_blob:
- new_parsed = self._parse_blob(item.b_blob, new_path)
-
- sym_diff = None
- if old_parsed and new_parsed:
- sym_diff = self._compute_symbol_diff(old_parsed, new_parsed)
- elif old_parsed:
- sym_diff = SymbolDiff(removed=list(old_parsed.symbols))
- elif new_parsed:
- sym_diff = SymbolDiff(added=list(new_parsed.symbols))
-
- results.append(
- FileDiff(
- path=path,
- status=status,
- old_path=old_path,
- old_parsed=old_parsed,
- new_parsed=new_parsed,
- symbol_diff=sym_diff,
+ stale.append(
+ FileDiff(
+ path=path,
+ status="deleted",
+ old_path=path,
+ old_parsed=None,
+ new_parsed=None,
+ symbol_diff=None,
+ )
)
- )
+ return stale
+
+ def _added_from_disk(
+ self,
+ path: str,
+ abs_path: Path,
+ status: Literal["added", "modified"] = "added",
+ ) -> FileDiff:
+ """A FileDiff whose new side is the file as it is on disk right now.
+
+ Used where there is no git blob to diff against: an untracked file,
+ and a file whose working-tree change has just been undone.
+ """
+ new_parsed = self._parse_path(abs_path, path)
+ return FileDiff(
+ path=path,
+ status=status,
+ old_path=None,
+ old_parsed=None,
+ new_parsed=new_parsed,
+ symbol_diff=SymbolDiff(added=list(new_parsed.symbols)) if new_parsed else None,
+ )
+
+ def _file_diff_from_item(self, item: object) -> FileDiff:
+ """Build a :class:`FileDiff` from one GitPython ``Diff``.
+
+ Shared by the commit-range and working-tree change sources so both
+ resolve status, old/new blobs and the symbol diff identically. The new
+ version is read from disk when the path exists there, which is what
+ makes the same code correct for a diff whose right-hand side *is* the
+ working tree.
+ """
+ status: Literal["added", "deleted", "modified", "renamed"]
+ old_path: str | None = None
+ new_path: str | None = None
+
+ change_type = item.change_type
+ if change_type == "A":
+ status = "added"
+ new_path = item.b_path
+ elif change_type == "D":
+ status = "deleted"
+ old_path = item.a_path
+ elif change_type == "R":
+ status = "renamed"
+ old_path = item.a_path
+ new_path = item.b_path
+ else:
+ status = "modified"
+ old_path = item.a_path
+ new_path = item.b_path
+
+ path = new_path or old_path or ""
+
+ # Parse old version (from git blob)
+ old_parsed = None
+ if old_path and item.a_blob:
+ old_parsed = self._parse_blob(item.a_blob, old_path)
+
+ # Parse new version (from working tree)
+ new_parsed = None
+ if new_path:
+ abs_path = self.repo_path / new_path
+ if abs_path.exists():
+ new_parsed = self._parse_path(abs_path, new_path)
+ elif item.b_blob:
+ new_parsed = self._parse_blob(item.b_blob, new_path)
+
+ sym_diff = None
+ if old_parsed and new_parsed:
+ sym_diff = self._compute_symbol_diff(old_parsed, new_parsed)
+ elif old_parsed:
+ sym_diff = SymbolDiff(removed=list(old_parsed.symbols))
+ elif new_parsed:
+ sym_diff = SymbolDiff(added=list(new_parsed.symbols))
+
+ return FileDiff(
+ path=path,
+ status=status,
+ old_path=old_path,
+ old_parsed=old_parsed,
+ new_parsed=new_parsed,
+ symbol_diff=sym_diff,
+ )
- return results
def detect_symbol_renames(
self,
@@ -439,3 +558,66 @@ class ChangeDetector:
renamed=renames,
modified=modified,
)
+
+
+def has_working_tree_changes(repo_path: Path) -> bool:
+ """Whether the working tree holds changes ``HEAD`` does not.
+
+ The same question :meth:`ChangeDetector.get_working_tree_changes` answers,
+ over the same paths, without parsing any of them. Callers that only need
+ the yes/no (a staleness check that runs on every watcher trigger) should
+ use this; parsing every changed and untracked source file just to learn
+ that one exists is the cost it avoids.
+
+ Repo resolution and the path filter deliberately match the detector's, or
+ the two would disagree: a "clean" verdict here followed by a non-empty
+ diff there is how a staleness gate skips work that exists.
+
+ False on a non-git directory or a repo with no commits yet.
+ """
+ try:
+ import git
+
+ repo = git.Repo(repo_path, search_parent_directories=True)
+ except Exception:
+ return False
+ try:
+ changed = (
+ item.b_path or item.a_path or "" for item in repo.head.commit.diff(None)
+ )
+ return any(
+ is_candidate_source_path(p.replace("\\", "/"))
+ for p in (*changed, *repo.untracked_files)
+ )
+ except Exception as exc:
+ log.warning("working tree check failed", path=str(repo_path), error=str(exc))
+ return False
+ finally:
+ repo.close()
+
+
+def merge_file_diffs(*sources: list[FileDiff]) -> list[FileDiff]:
+ """Union FileDiffs from several change sources, first mention winning.
+
+ Order matters: the commit-range diff is passed first because its
+ ``old_parsed`` is the last *indexed* version of the file, which is the
+ right baseline for a symbol diff. The working-tree diff's baseline is
+ ``HEAD``, so for a file that changed in both it would under-report what
+ the index has yet to see. Both already read the new version from disk, so
+ nothing is lost by preferring the earlier entry.
+
+ One exception: a deletion loses to any later source that says the file is
+ there. A commit can delete a path that the working tree then recreates,
+ and a deleted ``FileDiff`` carries ``new_parsed=None`` — keeping it would
+ tombstone the page and prune the symbols of a file that exists on disk
+ with content, until the recreation happened to be committed.
+ """
+ merged: dict[str, FileDiff] = {}
+ for source in sources:
+ for diff in source:
+ existing = merged.get(diff.path)
+ if existing is None or (
+ existing.status == "deleted" and diff.status != "deleted"
+ ):
+ merged[diff.path] = diff
+ return list(merged.values())
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 832a4a26b..6d8c7d2fd 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -181,6 +181,12 @@ _BLOCKED_FILENAME_PATTERNS: list[str] = [
"*.lock",
]
+#: ``_BLOCKED_FILENAME_PATTERNS`` compiled once. Matched against a bare
+#: filename, so it is equally usable from :func:`is_candidate_source_path`.
+_BLOCKED_FILENAME_SPEC: pathspec.PathSpec = pathspec.PathSpec.from_lines(
+ "gitwildmatch", _BLOCKED_FILENAME_PATTERNS
+)
+
# Generated file markers (checked in first 512 bytes)
_GENERATED_MARKERS: tuple[str, ...] = (
"Code generated",
@@ -266,9 +272,7 @@ class FileTraverser:
self._extra_ignore_filename = extra_ignore_filename
self._gitignore = _load_gitignore_spec(self.repo_root)
self._extra_ignore = _load_extra_ignore_spec(self.repo_root, extra_ignore_filename)
- self._blocked_patterns = pathspec.PathSpec.from_lines(
- "gitwildmatch", _BLOCKED_FILENAME_PATTERNS
- )
+ self._blocked_patterns = _BLOCKED_FILENAME_SPEC
patterns = extra_exclude_patterns or []
self._extra_exclude = _compile_gitignore(patterns)
# Per-directory ignore cache: absolute dir path -> PathSpec built from
@@ -855,6 +859,45 @@ def _parse_gitmodules(repo_root: Path) -> frozenset[str]:
return frozenset()
+def is_candidate_source_path(rel_path: str) -> bool:
+ """Whether *rel_path* is shaped like a file this repo would index.
+
+ Path-shape only: the directory blocklist, the blocked extensions/filename
+ patterns, and the known-language extension map. No disk access, no
+ gitignore, no binary/size/generated checks — so a ``True`` answer means
+ "worth handing to the pipeline", never "will be indexed". :class:`FileTraverser`
+ still applies the full test on the files it walks.
+
+ It exists for the two change sources that only ever see a path: the
+ working-tree diff (untracked files, which ``git`` reports without
+ consulting our blocklists) and the file watcher (which must not wake an
+ update for ``.git/index.lock`` or a ``node_modules`` write). Both were
+ reading the blocklists' intent by hand and drifting from it.
+
+ One known false negative: an extensionless script that :class:`FileTraverser`
+ accepts by shebang is rejected here, because deciding that means reading the
+ file and this must stay a pure path test. Such a file is indexed on a full
+ run and by any commit that touches it; only the two path-only sources above
+ miss it.
+ """
+ parts = Path(rel_path.replace("\\", "/")).parts
+ if not parts:
+ return False
+ if any(part in _BLOCKED_DIRS for part in parts[:-1]):
+ return False
+
+ name = parts[-1]
+ if name in SPECIAL_FILENAMES:
+ return True
+
+ suffix = Path(name).suffix.lower()
+ if suffix in _BLOCKED_EXTENSIONS:
+ return False
+ if _BLOCKED_FILENAME_SPEC.match_file(name):
+ return False
+ return suffix in EXTENSION_TO_LANGUAGE
+
+
def _compile_gitignore(lines: Iterable[str]) -> pathspec.PathSpec:
"""Build a gitwildmatch ``PathSpec``, tolerating malformed patterns.
diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.py
index 41d79c0cf..3a8430bc4 100644
--- a/packages/core/src/repowise/core/workspace/update.py
+++ b/packages/core/src/repowise/core/workspace/update.py
@@ -34,6 +34,7 @@ from repowise.core.update_lock import (
)
from ..docs_mode import docs_mode_state_fields
+from ..ingestion.change_detector import has_working_tree_changes
from .config import WorkspaceConfig
_log = logging.getLogger("repowise.workspace.update")
@@ -89,6 +90,12 @@ class RepoUpdateResult:
# KG; None means the persisted block is still current. State-file writes
# stay with the caller (_update_one), so the block rides on the result.
kg_state: dict[str, Any] | None = None
+ # Repo-relative paths this run indexed from the working tree rather than
+ # from a commit. Persisted as state.json "working_tree_paths" so the next
+ # run can tell which of them have since been reverted or deleted — working
+ # tree state has no ``last_sync_commit`` to diff against. None on the
+ # commit-anchored path, which leaves the stored list alone.
+ working_tree_paths: list[str] | None = None
# ---------------------------------------------------------------------------
@@ -332,6 +339,7 @@ async def _incremental_repo_update(
state: dict[str, Any],
base_ref: str,
exclude_patterns: list[str] | None = None,
+ include_working_tree: bool = False,
) -> RepoUpdateResult | None:
"""Refresh an already-indexed repo through the incremental update path.
@@ -346,7 +354,7 @@ async def _incremental_repo_update(
Raises on failure — the caller falls back to the full pipeline.
"""
- from ..ingestion.change_detector import ChangeDetector
+ from ..ingestion.change_detector import ChangeDetector, merge_file_diffs
from ..pipeline.incremental import (
persist_incremental_index,
rebuild_graph_and_git,
@@ -358,12 +366,30 @@ async def _incremental_repo_update(
head = get_head_commit(repo_path) or "HEAD"
detector = ChangeDetector(repo_path)
- file_diffs = detector.get_changed_files(base_ref, head)
+ working_tree_diffs: list = []
+ working_tree_paths: list[str] | None = None
+ if include_working_tree:
+ working_tree_diffs = detector.get_working_tree_changes()
+ dirty = {fd.path for fd in working_tree_diffs}
+ # Re-diff anything the last run indexed from the working tree that no
+ # longer diverges from HEAD, so a reverted edit or a deleted untracked
+ # file stops being served. See ``stale_working_tree_diffs``.
+ working_tree_diffs += detector.stale_working_tree_diffs(
+ state.get("working_tree_paths") or [], dirty
+ )
+ working_tree_paths = sorted(dirty)
+
+ file_diffs = merge_file_diffs(
+ detector.get_changed_files(base_ref, head),
+ working_tree_diffs,
+ )
if not file_diffs:
# New commits but nothing the index cares about changed (merge/empty
# commits, or every change excluded). Report success so the caller
# bumps ``last_sync_commit`` instead of re-diffing forever.
- return RepoUpdateResult(alias=alias, updated=True)
+ return RepoUpdateResult(
+ alias=alias, updated=True, working_tree_paths=working_tree_paths
+ )
# Per-repo config, like the single-repo update path. The workspace-level
# ``exclude_patterns`` (when provided) apply on top.
@@ -460,6 +486,7 @@ async def _incremental_repo_update(
file_count=file_count,
symbol_count=sum(len(pf.symbols) for pf in parsed_files),
kg_state=kg_state,
+ working_tree_paths=working_tree_paths,
)
@@ -468,6 +495,7 @@ async def update_single_repo_index(
*,
commit_depth: int = 500,
exclude_patterns: list[str] | None = None,
+ include_working_tree: bool = False,
progress: Any | None = None,
) -> RepoUpdateResult:
"""Refresh the index for a single repo.
@@ -516,6 +544,7 @@ async def update_single_repo_index(
state=state,
base_ref=str(base_ref),
exclude_patterns=exclude_patterns,
+ include_working_tree=include_working_tree,
)
if incremental_result is not None:
return incremental_result
@@ -579,6 +608,7 @@ async def update_workspace(
dry_run: bool = False,
commit_depth: int = 500,
exclude_patterns: list[str] | None = None,
+ include_working_tree: bool = False,
on_repo_start: Callable[[str], None] | None = None,
on_repo_done: Callable[[RepoUpdateResult], None] | None = None,
) -> list[RepoUpdateResult]:
@@ -599,6 +629,10 @@ async def update_workspace(
dry_run: If True, detect staleness but don't actually update.
commit_depth: Max commits to analyze per file.
exclude_patterns: Gitignore-style patterns to exclude.
+ include_working_tree: Count uncommitted work as staleness, and index
+ it. Off for every commit-anchored caller (hooks, webhooks, a
+ manual sync); ``repowise watch --workspace`` sets it, because a
+ repo it is watching normally has no new commits at all.
on_repo_start: Called with alias when a repo update begins.
on_repo_done: Called with result when a repo update finishes.
@@ -656,6 +690,12 @@ async def update_workspace(
stored_commit,
)
+ # A watched repo's changes are uncommitted by definition, so the
+ # commit-to-commit staleness check above says "up to date" for exactly
+ # the work the watcher woke up for.
+ if not is_stale and include_working_tree and has_working_tree_changes(abs_path):
+ is_stale = True
+
if not is_stale:
# Nothing to regenerate, but the DB freshness stamp can still be
# behind (e.g. a row left drifted by a pre-fix run). Reconcile it so
@@ -727,6 +767,7 @@ async def update_workspace(
path,
commit_depth=commit_depth,
exclude_patterns=exclude_patterns,
+ include_working_tree=include_working_tree,
)
finally:
_release_lock(path)
@@ -749,6 +790,8 @@ async def update_workspace(
state["last_sync_commit"] = new_head
if result.kg_state:
state["knowledge_graph"] = result.kg_state
+ if result.working_tree_paths is not None:
+ state["working_tree_paths"] = result.working_tree_paths
# Stamp the config fingerprint so the drift check in
# update_single_repo_index stays calibrated (and legacy repos
# without one stop re-triggering the full re-index).
diff --git a/tests/integration/test_cli.py b/tests/integration/test_cli.py
index 841935eb0..10e0c02bf 100644
--- a/tests/integration/test_cli.py
+++ b/tests/integration/test_cli.py
@@ -354,6 +354,165 @@ class TestUpdateIndexOnly:
assert state1["last_sync_commit"] != base_commit
+class TestUpdateWorkingTree:
+ """``repowise watch``'s change source: work that is on disk, not in git.
+
+ Without this the watcher was decorative — it fired an update on every save
+ and the update diffed commit-to-commit, which on a repo with no new commits
+ is empty by definition, so it printed "Already up to date" and returned.
+ """
+
+ def _symbol_names(self, repo):
+ import sqlite3
+
+ con = sqlite3.connect(repo / ".repowise" / "wiki.db")
+ try:
+ return {row[0] for row in con.execute("select name from wiki_symbols")}
+ finally:
+ con.close()
+
+ def _dirty(self, repo):
+ (repo / "new_module.py").write_text(
+ "def uncommitted_addition():\n return 1\n", encoding="utf-8"
+ )
+
+ def test_uncommitted_work_is_indexed(self, runner, git_work_repo):
+ from repowise.cli.commands.update_cmd.command import UpdateOutcome, run_update
+
+ r0 = runner.invoke(
+ cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False
+ )
+ assert r0.exit_code == 0, r0.output
+ assert "uncommitted_addition" not in self._symbol_names(git_work_repo)
+
+ self._dirty(git_work_repo)
+
+ outcome = run_update(
+ path=str(git_work_repo),
+ provider_name=None,
+ model=None,
+ since=None,
+ reasoning=None,
+ cascade_budget=None,
+ dry_run=False,
+ workspace=False,
+ no_workspace=True,
+ repo_alias=None,
+ index_only=True,
+ include_working_tree=True,
+ )
+
+ assert outcome is UpdateOutcome.REGENERATED
+ assert "uncommitted_addition" in self._symbol_names(git_work_repo)
+
+ def _wt_update(self, repo, *, release_lock=True):
+ """One watcher-style update. Mirrors ``_watch_single_repo``'s trigger,
+ lock release included — in-process repeat runs need it."""
+ from repowise.cli.commands.update_cmd.command import run_update
+ from repowise.cli.commands.watch_cmd import _release_own_update_lock
+
+ try:
+ return run_update(
+ path=str(repo),
+ provider_name=None,
+ model=None,
+ since=None,
+ reasoning=None,
+ cascade_budget=None,
+ dry_run=False,
+ workspace=False,
+ no_workspace=True,
+ repo_alias=None,
+ index_only=True,
+ include_working_tree=True,
+ )
+ finally:
+ if release_lock:
+ _release_own_update_lock(repo)
+
+ def _page_status(self, repo, path):
+ import sqlite3
+
+ con = sqlite3.connect(repo / ".repowise" / "wiki.db")
+ try:
+ row = con.execute(
+ "select freshness_status from wiki_pages where id = ?", (f"file_page:{path}",)
+ ).fetchone()
+ return row[0] if row else None
+ finally:
+ con.close()
+
+ def test_deleted_uncommitted_work_is_tombstoned(self, runner, git_work_repo):
+ """Working-tree state has no ``last_sync_commit`` to diff against: a
+ path stops being reported the moment it stops diverging from HEAD, so
+ without explicit tracking nothing would ever mention a deleted
+ untracked file again and its page would be served forever."""
+ r0 = runner.invoke(
+ cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False
+ )
+ assert r0.exit_code == 0, r0.output
+
+ self._dirty(git_work_repo)
+ self._wt_update(git_work_repo)
+ assert "uncommitted_addition" in self._symbol_names(git_work_repo)
+ assert self._page_status(git_work_repo, "new_module.py") != "tombstone"
+
+ (git_work_repo / "new_module.py").unlink()
+ self._wt_update(git_work_repo)
+
+ assert self._page_status(git_work_repo, "new_module.py") == "tombstone"
+
+ def test_the_lock_is_not_left_held_between_runs(self, runner, git_work_repo):
+ """The watcher is one long-lived process. ``run_update`` only drops
+ the single-flight lock at process exit, so without the watcher's own
+ release every save after the first would defer."""
+ from repowise.cli.commands.update_cmd.command import UpdateOutcome
+
+ r0 = runner.invoke(
+ cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False
+ )
+ assert r0.exit_code == 0, r0.output
+
+ self._dirty(git_work_repo)
+ assert self._wt_update(git_work_repo) is UpdateOutcome.REGENERATED
+
+ (git_work_repo / "second_module.py").write_text(
+ "def second_addition():\n return 2\n", encoding="utf-8"
+ )
+ # Without the release this is DEFERRED — the lock is held by this very
+ # process — and nothing after the first save is ever indexed.
+ assert self._wt_update(git_work_repo) is UpdateOutcome.REGENERATED
+ assert "second_addition" in self._symbol_names(git_work_repo)
+
+ def test_without_the_release_a_repeat_run_defers(self, runner, git_work_repo):
+ """Pins the failure mode the release exists for."""
+ from repowise.cli.commands.update_cmd.command import UpdateOutcome
+
+ runner.invoke(cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False)
+ self._dirty(git_work_repo)
+ self._wt_update(git_work_repo, release_lock=False)
+
+ assert self._wt_update(git_work_repo) is UpdateOutcome.DEFERRED
+
+ def test_commit_anchored_update_is_unchanged(self, runner, git_work_repo):
+ """The default stays commit-to-commit: hooks and webhooks must not
+ start indexing whatever half-finished edit happens to be on disk."""
+ r0 = runner.invoke(
+ cli, ["init", str(git_work_repo), "--index-only"], catch_exceptions=False
+ )
+ assert r0.exit_code == 0, r0.output
+
+ self._dirty(git_work_repo)
+
+ r1 = runner.invoke(
+ cli, ["update", str(git_work_repo), "--index-only"], catch_exceptions=False
+ )
+
+ assert r1.exit_code == 0, r1.output
+ assert "Already up to date" in r1.output
+ assert "uncommitted_addition" not in self._symbol_names(git_work_repo)
+
+
class TestUpdateConfigChangeDetection:
def _state(self, repo):
import json
diff --git a/tests/unit/cli/test_watch_cmd.py b/tests/unit/cli/test_watch_cmd.py
index 5bf5d4c8a..b8c8ea834 100644
--- a/tests/unit/cli/test_watch_cmd.py
+++ b/tests/unit/cli/test_watch_cmd.py
@@ -2,6 +2,11 @@
from __future__ import annotations
+import os
+import threading
+import time
+from pathlib import Path
+
import click
import pytest
from click.testing import CliRunner
@@ -77,4 +82,203 @@ def test_watch_forwards_logging_mode_to_single_repo_updates(
)
assert result.exit_code == 0
- assert calls == [(tmp_path, "demo-provider", "demo-model", 750, expected_verbose)]
+ assert calls == [(tmp_path, "demo-provider", "demo-model", 750, expected_verbose, False)]
+
+
+def test_watch_forwards_index_only(monkeypatch: pytest.MonkeyPatch, tmp_path) -> None:
+ calls: list[tuple[object, ...]] = []
+ monkeypatch.setattr(watch_cmd, "configure_cli_logging", lambda **_kwargs: None)
+ monkeypatch.setattr(
+ watch_cmd,
+ "resolve_command_target",
+ lambda **_kwargs: CommandTarget(mode="single", repo_path=tmp_path),
+ )
+ monkeypatch.setattr(watch_cmd, "_watch_single_repo", lambda *args: calls.append(args))
+
+ result = CliRunner().invoke(cli, ["watch", "--index-only"])
+
+ assert result.exit_code == 0
+ assert calls == [(tmp_path, None, None, 2000, False, True)]
+
+
+class TestIsWatchablePath:
+ """Which filesystem events are worth waking an update for."""
+
+ @pytest.mark.parametrize("path", ["src/app.py", "packages/ui/index.ts", "README.md"])
+ def test_source_files_wake_an_update(self, path: str) -> None:
+ assert watch_cmd.is_watchable_path(path) is True
+
+ @pytest.mark.parametrize(
+ "path",
+ [
+ # The traversal blocklist: an `npm install` or a build must not
+ # mean thousands of triggers.
+ "node_modules/left-pad/index.js",
+ "dist/bundle.js",
+ ".git/index.lock",
+ ".repowise/state.json",
+ "uv.lock",
+ ],
+ )
+ def test_ignored_paths(self, path: str) -> None:
+ assert watch_cmd.is_watchable_path(path) is False
+
+ @pytest.mark.parametrize(
+ "path",
+ ["CLAUDE.md", "AGENTS.md", ".mcp.json", ".claude/CLAUDE.md", ".cursor/mcp.json"],
+ )
+ def test_files_repowise_writes_itself_do_not_retrigger(self, path: str) -> None:
+ # Every update re-stamps these. Treating them as user edits would make
+ # each update schedule the next one, forever.
+ assert watch_cmd.is_watchable_path(path) is False
+
+ def test_windows_separators(self) -> None:
+ assert watch_cmd.is_watchable_path(r"src\app.py") is True
+ assert watch_cmd.is_watchable_path(r".claude\CLAUDE.md") is False
+
+
+class TestSingleRepoTrigger:
+ """What the debounced trigger actually runs."""
+
+ def _fire(self, monkeypatch: pytest.MonkeyPatch, tmp_path, **watch_kwargs):
+ """Start the watcher, touch a file, and return run_update's kwargs."""
+ calls: list[dict] = []
+ done = threading.Event()
+
+ def fake_run_update(**kwargs):
+ calls.append(kwargs)
+ done.set()
+
+ monkeypatch.setattr(
+ "repowise.cli.commands.update_cmd.command.run_update", fake_run_update
+ )
+ monkeypatch.setattr(watch_cmd, "ensure_repowise_dir", lambda _p: None)
+
+ started = threading.Event()
+
+ class _Clock:
+ """Stands in for the ``time`` module inside watch_cmd only.
+
+ The watcher's idle loop is ``while True: time.sleep(1)``; this lets
+ the test break out of it once the update has been observed, instead
+ of leaving an Observer thread running for the rest of the session.
+ """
+
+ @staticmethod
+ def sleep(_seconds: float) -> None:
+ started.set()
+ time.sleep(0.01)
+ if done.is_set():
+ raise KeyboardInterrupt
+
+ monkeypatch.setattr(watch_cmd, "time", _Clock)
+
+ watcher = threading.Thread(
+ target=watch_cmd._watch_single_repo,
+ args=(tmp_path, None, None, 50, False),
+ kwargs=watch_kwargs,
+ daemon=True,
+ )
+ watcher.start()
+ assert started.wait(5), "watcher never started"
+
+ (tmp_path / "touched.py").write_text("def x():\n return 1\n", encoding="utf-8")
+ assert done.wait(10), "no update was triggered by the file change"
+ watcher.join(timeout=10)
+ return calls
+
+ def test_a_file_save_runs_an_update_over_the_working_tree(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path
+ ) -> None:
+ calls = self._fire(monkeypatch, tmp_path)
+
+ assert len(calls) == 1
+ # The bug this guards: watch fired an update per save, and the update
+ # only ever diffed commit-to-commit, so nothing the watcher saw was
+ # ever indexed until the user committed.
+ assert calls[0]["include_working_tree"] is True
+ assert calls[0]["path"] == str(tmp_path)
+ assert calls[0]["index_only"] is False
+
+ def test_index_only_is_passed_through(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path
+ ) -> None:
+ calls = self._fire(monkeypatch, tmp_path, index_only=True)
+
+ assert calls[0]["index_only"] is True
+
+
+class TestReleaseOwnUpdateLock:
+ """``run_update`` only gives the single-flight lock back at process exit.
+
+ Fine for a one-shot CLI run; for a watcher it means the second save finds
+ a live lock owned by its own PID and defers, and every save after the
+ first is a no-op for the rest of the session.
+ """
+
+ def test_a_lock_this_process_owns_is_released(self, tmp_path) -> None:
+ from repowise.core.update_lock import try_acquire_update_lock, update_lock_path
+
+ assert try_acquire_update_lock(tmp_path, "abc123") is None
+ assert update_lock_path(tmp_path).exists()
+
+ watch_cmd._release_own_update_lock(tmp_path)
+
+ assert not update_lock_path(tmp_path).exists()
+
+ def test_another_process_lock_is_left_alone(self, tmp_path) -> None:
+ import json
+
+ from repowise.core.update_lock import update_lock_path
+
+ lock = update_lock_path(tmp_path)
+ lock.parent.mkdir(parents=True, exist_ok=True)
+ # A live PID that is not ours: PID 1-style payloads are probed for
+ # liveness, so use this process's parent-agnostic marker instead —
+ # any pid we do not own must survive.
+ lock.write_text(
+ json.dumps({"pid": os.getpid() + 1, "target_commit": "x", "started_at": time.time()}),
+ encoding="utf-8",
+ )
+
+ watch_cmd._release_own_update_lock(tmp_path)
+
+ assert lock.exists()
+
+ def test_no_lock_is_not_an_error(self, tmp_path) -> None:
+ watch_cmd._release_own_update_lock(tmp_path)
+
+
+class TestEventPaths:
+ """Which paths a filesystem event contributes."""
+
+ class _Event:
+ def __init__(self, src_path: str, dest_path: str | None = None) -> None:
+ self.src_path = src_path
+ self.dest_path = dest_path
+
+ def test_a_plain_write(self, tmp_path) -> None:
+ event = self._Event(str(tmp_path / "src" / "app.py"))
+
+ assert watch_cmd._event_paths(event, tmp_path) == {str(Path("src") / "app.py")}
+
+ def test_an_atomic_save_is_seen_through_its_destination(self, tmp_path) -> None:
+ # JetBrains IDEs, Vim and many Windows editors save by writing a temp
+ # file and renaming it over the target. Reading src_path alone drops
+ # the save entirely.
+ event = self._Event(
+ str(tmp_path / "app.py~RF1a2b.TMP"),
+ dest_path=str(tmp_path / "app.py"),
+ )
+
+ assert watch_cmd._event_paths(event, tmp_path) == {"app.py"}
+
+ def test_paths_outside_the_root_are_dropped_not_raised(self, tmp_path) -> None:
+ event = self._Event(str(tmp_path.parent / "elsewhere" / "app.py"))
+
+ assert watch_cmd._event_paths(event, tmp_path) == set()
+
+ def test_ignored_paths_contribute_nothing(self, tmp_path) -> None:
+ event = self._Event(str(tmp_path / ".repowise" / "state.json"))
+
+ assert watch_cmd._event_paths(event, tmp_path) == set()
diff --git a/tests/unit/ingestion/test_working_tree_changes.py b/tests/unit/ingestion/test_working_tree_changes.py
new file mode 100644
index 000000000..21bf3ae9e
--- /dev/null
+++ b/tests/unit/ingestion/test_working_tree_changes.py
@@ -0,0 +1,267 @@
+"""Working-tree change detection — what ``repowise watch`` runs on.
+
+``get_changed_files`` diffs commit to commit, so a repo whose only changes are
+uncommitted reads as unchanged: the watcher fired an update per file save and
+every one of them was a no-op. These cover the source that answers the other
+question — what is on disk that ``HEAD`` does not have.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import git as gitpython
+import pytest
+
+from repowise.core.ingestion.change_detector import (
+ ChangeDetector,
+ FileDiff,
+ has_working_tree_changes,
+ merge_file_diffs,
+)
+from repowise.core.ingestion.traverser import is_candidate_source_path
+
+
+def repo(tmp_path: Path) -> Path:
+ """A one-commit git repo with two python files."""
+ r = gitpython.Repo.init(tmp_path)
+ with r.config_writer() as cw:
+ cw.set_value("user", "name", "Alice")
+ cw.set_value("user", "email", "[email protected]")
+ (tmp_path / "main.py").write_text("def alpha():\n return 1\n", encoding="utf-8")
+ (tmp_path / "util.py").write_text("def helper():\n return 2\n", encoding="utf-8")
+ r.index.add(["main.py", "util.py"])
+ r.index.commit("init")
+ r.close()
+ return tmp_path
+
+
+def _by_path(diffs: list[FileDiff]) -> dict[str, FileDiff]:
+ return {d.path: d for d in diffs}
+
+
+class TestGetWorkingTreeChanges:
+ def test_clean_tree_reports_nothing(self, repo: Path) -> None:
+ assert ChangeDetector(repo).get_working_tree_changes() == []
+
+ def test_unstaged_edit_is_a_modification(self, repo: Path) -> None:
+ (repo / "main.py").write_text(
+ "def alpha():\n return 1\n\n\ndef beta():\n return 2\n", encoding="utf-8"
+ )
+
+ diffs = _by_path(ChangeDetector(repo).get_working_tree_changes())
+
+ assert diffs["main.py"].status == "modified"
+ # The new side is read from disk, so the symbol the user just typed
+ # is in the diff — this is the content the index has to pick up.
+ assert diffs["main.py"].new_parsed is not None
+ assert {s.name for s in diffs["main.py"].new_parsed.symbols} == {"alpha", "beta"}
+ assert [s.name for s in diffs["main.py"].symbol_diff.added] == ["beta"]
+
+ def test_staged_edit_is_reported_too(self, repo: Path) -> None:
+ (repo / "main.py").write_text("def gamma():\n return 3\n", encoding="utf-8")
+ r = gitpython.Repo(repo)
+ r.index.add(["main.py"])
+ r.close()
+
+ diffs = _by_path(ChangeDetector(repo).get_working_tree_changes())
+
+ assert diffs["main.py"].status == "modified"
+
+ def test_untracked_source_file_is_an_addition(self, repo: Path) -> None:
+ (repo / "brand_new.py").write_text("def fresh():\n return 4\n", encoding="utf-8")
+
+ diffs = _by_path(ChangeDetector(repo).get_working_tree_changes())
+
+ assert diffs["brand_new.py"].status == "added"
+ assert diffs["brand_new.py"].old_parsed is None
+ assert [s.name for s in diffs["brand_new.py"].symbol_diff.added] == ["fresh"]
+
+ def test_deleted_file_is_a_deletion(self, repo: Path) -> None:
+ (repo / "util.py").unlink()
+
+ diffs = _by_path(ChangeDetector(repo).get_working_tree_changes())
+
+ assert diffs["util.py"].status == "deleted"
+ assert diffs["util.py"].new_parsed is None
+
+ def test_untracked_paths_the_index_would_skip_are_dropped(self, repo: Path) -> None:
+ # repowise's own state dir is the one that matters: it changes on every
+ # update, so letting it through would make each update schedule the next.
+ (repo / ".repowise").mkdir()
+ (repo / ".repowise" / "state.json").write_text("{}", encoding="utf-8")
+ (repo / "node_modules" / "dep").mkdir(parents=True)
+ (repo / "node_modules" / "dep" / "index.js").write_text("x", encoding="utf-8")
+ (repo / "app.log").write_text("noise", encoding="utf-8")
+
+ paths = {d.path for d in ChangeDetector(repo).get_working_tree_changes()}
+
+ assert paths == set()
+
+ def test_gitignored_files_never_appear(self, repo: Path) -> None:
+ (repo / ".gitignore").write_text("secret.py\n", encoding="utf-8")
+ (repo / "secret.py").write_text("KEY = 'x'\n", encoding="utf-8")
+ (repo / "visible.py").write_text("KEY = 'y'\n", encoding="utf-8")
+
+ paths = {d.path for d in ChangeDetector(repo).get_working_tree_changes()}
+
+ assert paths == {"visible.py"}
+
+ def test_non_git_directory_is_empty_not_an_error(self, tmp_path: Path) -> None:
+ (tmp_path / "loose.py").write_text("x = 1\n", encoding="utf-8")
+
+ assert ChangeDetector(tmp_path).get_working_tree_changes() == []
+
+ def test_tracked_changes_the_index_would_skip_are_dropped(self, repo: Path) -> None:
+ # A tracked lockfile churning must not mark the repo dirty: it would
+ # drive a full graph rebuild with nothing to index at the end of it.
+ (repo / "uv.lock").write_text("v = 1\n", encoding="utf-8")
+ r = gitpython.Repo(repo)
+ r.index.add(["uv.lock"])
+ r.index.commit("add lock")
+ r.close()
+ (repo / "uv.lock").write_text("v = 2\n", encoding="utf-8")
+
+ assert ChangeDetector(repo).get_working_tree_changes() == []
+
+
+class TestHasWorkingTreeChanges:
+ def test_false_on_a_clean_tree(self, repo: Path) -> None:
+ assert has_working_tree_changes(repo) is False
+
+ def test_true_for_a_tracked_edit(self, repo: Path) -> None:
+ (repo / "main.py").write_text("def alpha():\n return 99\n", encoding="utf-8")
+
+ assert has_working_tree_changes(repo) is True
+
+ def test_true_for_an_untracked_source_file(self, repo: Path) -> None:
+ (repo / "new.py").write_text("x = 1\n", encoding="utf-8")
+
+ assert has_working_tree_changes(repo) is True
+
+ def test_ignorable_untracked_noise_does_not_count(self, repo: Path) -> None:
+ (repo / ".repowise").mkdir()
+ (repo / ".repowise" / "state.json").write_text("{}", encoding="utf-8")
+
+ assert has_working_tree_changes(repo) is False
+
+ def test_agrees_with_the_detector_on_ignorable_tracked_churn(self, repo: Path) -> None:
+ # The two must not disagree: a "clean" verdict here followed by a
+ # non-empty diff there is how a staleness gate skips real work.
+ (repo / "uv.lock").write_text("v = 1\n", encoding="utf-8")
+ r = gitpython.Repo(repo)
+ r.index.add(["uv.lock"])
+ r.index.commit("add lock")
+ r.close()
+ (repo / "uv.lock").write_text("v = 2\n", encoding="utf-8")
+
+ assert has_working_tree_changes(repo) is False
+ assert ChangeDetector(repo).get_working_tree_changes() == []
+
+ def test_false_on_a_non_git_directory(self, tmp_path: Path) -> None:
+ assert has_working_tree_changes(tmp_path) is False
+
+
+def _diff(path: str, status: str) -> FileDiff:
+ return FileDiff(
+ path=path,
+ status=status, # type: ignore[arg-type]
+ old_path=None,
+ old_parsed=None,
+ new_parsed=None,
+ symbol_diff=None,
+ )
+
+
+class TestMergeFileDiffs:
+ def test_first_source_wins_for_a_path_in_both(self) -> None:
+ commit_side = _diff("a.py", "modified")
+ working_side = _diff("a.py", "added")
+
+ merged = merge_file_diffs([commit_side], [working_side])
+
+ # The commit-range entry is baselined at the last indexed commit; the
+ # working-tree one only reaches back to HEAD.
+ assert merged == [commit_side]
+
+ def test_paths_from_either_source_are_kept(self) -> None:
+ merged = merge_file_diffs([_diff("a.py", "modified")], [_diff("b.py", "added")])
+
+ assert {d.path for d in merged} == {"a.py", "b.py"}
+
+ def test_a_deletion_loses_to_a_later_source_that_has_the_file(self) -> None:
+ # Committed `git rm foo.py`, then recreated in the working tree.
+ # Keeping the deletion would tombstone a file that exists on disk.
+ merged = merge_file_diffs([_diff("foo.py", "deleted")], [_diff("foo.py", "added")])
+
+ assert [d.status for d in merged] == ["added"]
+
+ def test_a_deletion_still_wins_over_a_later_deletion(self) -> None:
+ commit_side = _diff("foo.py", "deleted")
+ merged = merge_file_diffs([commit_side], [_diff("foo.py", "deleted")])
+
+ assert merged == [commit_side]
+
+
+class TestStaleWorkingTreeDiffs:
+ """Undoing working-tree work the index has already taken in."""
+
+ def test_a_deleted_untracked_file_comes_back_as_a_deletion(self, repo: Path) -> None:
+ # Indexed while it existed; now gone, and nothing else would ever
+ # mention it again.
+ diffs = ChangeDetector(repo).stale_working_tree_diffs(["gone.py"], set())
+
+ assert [(d.path, d.status) for d in diffs] == [("gone.py", "deleted")]
+
+ def test_a_reverted_edit_is_re_read_from_disk(self, repo: Path) -> None:
+ # main.py was indexed with an uncommitted edit that has since been
+ # reverted: the index holds symbols the file no longer has.
+ diffs = ChangeDetector(repo).stale_working_tree_diffs(["main.py"], set())
+
+ assert [(d.path, d.status) for d in diffs] == [("main.py", "modified")]
+ assert [s.name for s in diffs[0].new_parsed.symbols] == ["alpha"]
+
+ def test_paths_still_dirty_are_left_alone(self, repo: Path) -> None:
+ assert ChangeDetector(repo).stale_working_tree_diffs(["main.py"], {"main.py"}) == []
+
+
+class TestIsCandidateSourcePath:
+ @pytest.mark.parametrize(
+ "path",
+ [
+ "src/app.py",
+ "packages/ui/index.ts",
+ "Dockerfile",
+ "README.md",
+ "deep/nested/mod.go",
+ ],
+ )
+ def test_source_paths(self, path: str) -> None:
+ assert is_candidate_source_path(path) is True
+
+ @pytest.mark.parametrize(
+ "path",
+ [
+ ".repowise/state.json",
+ ".git/index",
+ "node_modules/left-pad/index.js",
+ "dist/bundle.js",
+ "build/out.js",
+ ".venv/lib/x.py",
+ "package-lock.json",
+ "uv.lock",
+ "app.pyc",
+ "notes.txt.bak",
+ "logo.png",
+ ],
+ )
+ def test_non_source_paths(self, path: str) -> None:
+ assert is_candidate_source_path(path) is False
+
+ def test_windows_separators_are_understood(self) -> None:
+ assert is_candidate_source_path(r"src\app.py") is True
+ assert is_candidate_source_path(r".repowise\state.json") is False
+
+ def test_empty_path(self) -> None:
+ assert is_candidate_source_path("") is False