feat(ui): warn when include patterns defeat directory pruning (#162)

## What

Both places a user edits exclusion rules - the add-source wizard's
Exclusions step and the per-source inline editor in Settings > Sources -
now show a small amber warning box under the **Include patterns**
textarea whenever an entered include pattern would stop the scanner from
pruning excluded directories.

The scanner can only skip descending into an excluded folder
(`node_modules`, etc.) when it can prove no include pattern could match
inside it. That proof needs a root-anchored pattern of bounded depth
(`/repo/.env`, `/*/.env`, `/a/*/b/.env`). A relative pattern (`.env`,
`*/.env`, `blah/.env`) matches at any depth, and one containing `**`
spans any number of levels - either forces the walk into every excluded
directory just in case, which is what makes a scan crawl.

## How

- `ui/src/stores/exclusionPreview.ts` (where the other pattern helpers
live) gains `isUnconstrainedIncludePattern` /
`unconstrainedIncludePatterns`: a trimmed, non-empty pattern is
unconstrained iff it does not start with `/` **or** it contains `**`.
`splitPatterns` is now exported from the same module and both editors
use it instead of their own private copies, so the warning splits input
exactly the way the saved rules do (newline **or** comma separated).
- Each editor renders the box reactively off a `computed` over its
textarea text, so it appears/disappears as the user types - the preview
walk still only re-runs on blur. The box names the offending patterns
and links to the anchored forms; styling matches the existing amber
warning surfaces (`AccountList` reauth banner, `PausedBanner`).
- New i18n keys nested under `settings.addSource.includeWarning`
(`title`, `hint`), shared by both editors like the existing
`includePatternsLabel`.

## Tests

- `exclusion-preview-store.test.ts`: a vector table for the helper
(`.env`, `*/.env`, `blah/.env`, `/*/x/**/.env` warn; `/x/.env`,
`/*/.env`, `/a/*/b/.env` do not), plus trimming, blank lines, and comma
vs newline splitting.
- `settings-components.test.ts`: one test per editor asserting the box
is absent with no rules, appears listing **only** the offending patterns
once an unconstrained rule is typed, and disappears when the rules are
anchored - without a blur or a re-preview.

`npx vitest run` 454 passed, `prettier --check src` clean, `vue-tsc
--noEmit` and `eslint .` clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01JLB3E2Jm7knNJd37fVpH8X

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: pmaxhogan

ui/src/__tests__/exclusion-preview-store.test.ts

@@ -35,6 +35,8 @@ import {
   anchoredPatternForPath,
   appendPatternLine,
   createExclusionPreview,
+  isUnconstrainedIncludePattern,
+  unconstrainedIncludePatterns,
   type ExclusionPreviewController,
 } from "../stores/exclusionPreview";
 import type { ExclusionPreviewBatch, ExclusionPreviewNode } from "../ipc/types";
@@ -128,6 +130,67 @@ describe("appendPatternLine", () => {
   });
 });
 
+describe("isUnconstrainedIncludePattern", () => {
+  // The scanner may only PRUNE an excluded directory when no include pattern
+  // could match beneath it, which needs a root-anchored pattern of bounded
+  // depth. Anything relative, or spanning levels with a double-star, forces the
+  // walk into every excluded folder - those are the ones the editors warn about.
+  const vectors: Array<[string, boolean]> = [
+    // Unconstrained: no leading slash, so it matches at any depth.
+    [".env", true],
+    ["*/.env", true],
+    ["blah/.env", true],
+    ["**/.env", true],
+    // Unconstrained: anchored, but a double-star spans any number of levels.
+    ["/*/x/**/.env", true],
+    ["/**", true],
+    ["/a/**/b", true],
+    // Constrained: anchored AND depth-bounded.
+    ["/x/.env", false],
+    ["/*/.env", false],
+    ["/a/*/b/.env", false],
+    ["/.env", false],
+    ["/node_modules/", false],
+    // Blank lines are not patterns at all.
+    ["", false],
+    ["   ", false],
+  ];
+
+  it.each(vectors)("treats %j as unconstrained=%s", (pattern, expected) => {
+    expect(isUnconstrainedIncludePattern(pattern)).toBe(expected);
+  });
+
+  it("judges a pattern by its trimmed form", () => {
+    // The editors trim each line before sending it, so surrounding whitespace
+    // must not change the verdict either way.
+    expect(isUnconstrainedIncludePattern("  /x/.env  ")).toBe(false);
+    expect(isUnconstrainedIncludePattern("  .env  ")).toBe(true);
+  });
+});
+
+describe("unconstrainedIncludePatterns", () => {
+  it("reports only the offending patterns, in the order they were typed", () => {
+    expect(unconstrainedIncludePatterns("/x/.env\n.env\n/a/*/b/.env\n/*/x/**/.env")).toEqual([
+      ".env",
+      "/*/x/**/.env",
+    ]);
+  });
+
+  it("splits on commas as well as newlines, the way both editors do", () => {
+    expect(unconstrainedIncludePatterns("/x/.env,blah/.env,/*/.env")).toEqual(["blah/.env"]);
+  });
+
+  it("ignores blank lines and surrounding whitespace", () => {
+    expect(unconstrainedIncludePatterns("\n  \n  /x/.env  \n\n,, \t\n")).toEqual([]);
+    expect(unconstrainedIncludePatterns("  */.env  \n\n")).toEqual(["*/.env"]);
+  });
+
+  it("is empty for empty input and for an all-anchored list", () => {
+    expect(unconstrainedIncludePatterns("")).toEqual([]);
+    expect(unconstrainedIncludePatterns("/x/.env\n/*/.env\n/a/*/b/.env")).toEqual([]);
+  });
+});
+
 describe("createExclusionPreview", () => {
   it("starts a streaming preview and reports it as scanning", async () => {
     const preview = await started();

ui/src/__tests__/settings-components.test.ts

@@ -444,6 +444,44 @@ describe("SourceTable", () => {
     );
   });
 
+  it("warns while typing an include pattern that defeats directory pruning", async () => {
+    // The scanner can only skip descending into an excluded folder when no
+    // include rule could match beneath it. A relative rule (or one with a
+    // double-star) forces it into every node_modules, so the editor calls that
+    // out AS THE USER TYPES - the preview walk only re-runs on blur, and the
+    // guidance must not wait for it.
+    invokeMock.mockImplementation((cmd: string) => {
+      if (cmd === "list_sources") return Promise.resolve([makeSource()]);
+      if (cmd === "list_accounts") return Promise.resolve([]);
+      if (cmd === "preview_exclusions_start") return Promise.resolve("gen-1");
+      return Promise.resolve(undefined);
+    });
+    const wrapper = mount(SourceTable, { global: globalMountOptions });
+    await flushPromises();
+    await wrapper
+      .findAll("button")
+      .find((b) => b.text() === i18n.global.t("settings.sources.editExclusionsButton"))!
+      .trigger("click");
+    await flushPromises();
+
+    const editor = wrapper.get('[data-testid="exclusion-editor"]');
+    // A source with no include rules at all has nothing to warn about.
+    expect(wrapper.find('[data-testid="include-pattern-warning"]').exists()).toBe(false);
+
+    const includeArea = editor.findAll("textarea")[0];
+    await includeArea.setValue("/keep/.env\n.env\n/*/x/**/.env");
+    const warning = wrapper.get('[data-testid="include-pattern-warning"]');
+    expect(warning.text()).toContain(i18n.global.t("settings.addSource.includeWarning.title"));
+    // Only the offending rules are listed - the anchored, depth-bounded one is
+    // fine and must not be named.
+    const listed = warning.findAll("li").map((li) => li.text());
+    expect(listed).toEqual([".env", "/*/x/**/.env"]);
+
+    // Anchoring them clears the box without a blur or a re-preview.
+    await includeArea.setValue("/keep/.env\n/*/.env");
+    expect(wrapper.find('[data-testid="include-pattern-warning"]').exists()).toBe(false);
+  });
+
   it("Edit exclusions opens the inline editor and saves a patch", async () => {
     invokeMock.mockImplementation((cmd: string) => {
       if (cmd === "list_sources") return Promise.resolve([makeSource()]);
@@ -747,6 +785,61 @@ describe("AddSourceWizard", () => {
     );
   });
 
+  it("warns on the exclusions step when an include pattern defeats directory pruning", async () => {
+    invokeMock.mockImplementation((cmd: string) => {
+      if (cmd === "list_accounts")
+        return Promise.resolve([
+          {
+            id: "acc-1",
+            email: "user@example.com",
+            displayName: null,
+            state: "ok",
+            encryptionEnabled: false,
+            createdAt: 0,
+            lastSyncedAt: null,
+          },
+        ]);
+      if (cmd === "pick_drive_folder")
+        return Promise.resolve({ currentFolderId: "root", currentFolderPath: "", folders: [] });
+      if (cmd === "preview_exclusions_start") return Promise.resolve("gen-1");
+      if (cmd === "pick_folder_dialog")
+        return Promise.resolve({ path: "/home/u/docs", token: "tok-folder" });
+      return Promise.resolve(undefined);
+    });
+
+    const wrapper = mount(AddSourceWizard, { global: globalMountOptions });
+    await (wrapper.vm as unknown as { start: () => Promise<void> }).start();
+    await flushPromises();
+    await wrapper
+      .findAll("button")
+      .find((b) => b.text() === i18n.global.t("settings.addSource.chooseLocalButton"))!
+      .trigger("click");
+    await flushPromises();
+    const clickNext = async () => {
+      await wrapper
+        .findAll("button")
+        .find((b) => b.text() === i18n.global.t("common.next"))!
+        .trigger("click");
+      await flushPromises();
+    };
+    await clickNext(); // -> Drive
+    await clickNext(); // -> Exclusions
+
+    // A fresh wizard starts with no rules, so nothing to warn about.
+    expect(wrapper.find('[data-testid="include-pattern-warning"]').exists()).toBe(false);
+
+    const includeArea = wrapper.findAll("textarea")[0];
+    await includeArea.setValue("blah/.env,/a/*/b/.env");
+    const warning = wrapper.get('[data-testid="include-pattern-warning"]');
+    expect(warning.text()).toContain(i18n.global.t("settings.addSource.includeWarning.hint"));
+    expect(warning.findAll("li").map((li) => li.text())).toEqual(["blah/.env"]);
+
+    // Anchoring the rule clears the box, and typing never triggered a re-walk
+    // (that still belongs to blur).
+    await includeArea.setValue("/blah/.env,/a/*/b/.env");
+    expect(wrapper.find('[data-testid="include-pattern-warning"]').exists()).toBe(false);
+  });
+
   it("issue #4: checking the cloud-only toggle sends placeholderPolicy force_download; default is skip", async () => {
     let addArgs: unknown = null;
     invokeMock.mockImplementation((cmd: string, args?: unknown) => {

ui/src/components/AddSourceWizard.vue

@@ -8,7 +8,11 @@ import RecoveryPhraseReveal from "./RecoveryPhraseReveal.vue";
 import * as ipc from "../ipc/commands";
 import { toErrorCode } from "../ipc/errors";
 import { useAccountsStore } from "../stores/accounts";
-import { appendPatternLine } from "../stores/exclusionPreview";
+import {
+  appendPatternLine,
+  splitPatterns,
+  unconstrainedIncludePatterns,
+} from "../stores/exclusionPreview";
 import { useSourcesStore } from "../stores/sources";
 import type { SourceDto } from "../ipc/types";
 
@@ -105,17 +109,16 @@ const revealErrorCode = ref<string | null>(null);
 
 const includePatterns = computed(() => splitPatterns(includePatternsText.value));
 const excludePatterns = computed(() => splitPatterns(excludePatternsText.value));
+// The include rules that stop the scanner from pruning excluded folders, so the
+// exclusions step can warn about them AS THEY ARE TYPED (the walk itself only
+// re-runs on blur, but the guidance should not wait for it).
+const unconstrainedIncludes = computed(() =>
+  unconstrainedIncludePatterns(includePatternsText.value)
+);
 
 const canLeaveLocal = computed(() => accountId.value !== null && localPathToken.value !== null);
 const canLeaveDrive = computed(() => driveFolderId.value !== null);
 
-function splitPatterns(text: string): string[] {
-  return text
-    .split(/[\n,]/)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0);
-}
-
 async function start(): Promise<void> {
   reset();
   open.value = true;
@@ -402,6 +405,26 @@ defineExpose({ start });
             @blur="refreshPreview"
           />
         </label>
+        <!-- An include rule the scanner cannot bound to a fixed depth forces it
+             into every excluded folder, so the walk stops being prunable. -->
+        <div
+          v-if="unconstrainedIncludes.length > 0"
+          class="rounded-lg border border-amber-400 bg-amber-50 p-3 text-xs text-amber-800 dark:border-amber-700 dark:bg-amber-950/40 dark:text-amber-200"
+          data-testid="include-pattern-warning"
+          role="status"
+        >
+          <p class="font-medium">
+            {{ t("settings.addSource.includeWarning.title") }}
+          </p>
+          <ul class="mt-1 list-disc space-y-0.5 pl-5 font-mono break-all">
+            <li v-for="pattern in unconstrainedIncludes" :key="pattern">
+              {{ pattern }}
+            </li>
+          </ul>
+          <p class="mt-2">
+            {{ t("settings.addSource.includeWarning.hint") }}
+          </p>
+        </div>
         <label class="block space-y-1 text-sm">
           <span class="text-zinc-600 dark:text-zinc-400">{{
             t("settings.addSource.excludePatternsLabel")

ui/src/components/SourceTable.vue

@@ -8,7 +8,11 @@ import RecoveryPhraseReveal from "./RecoveryPhraseReveal.vue";
 import * as ipc from "../ipc/commands";
 import { toErrorCode } from "../ipc/errors";
 import { useAccountsStore } from "../stores/accounts";
-import { appendPatternLine } from "../stores/exclusionPreview";
+import {
+  appendPatternLine,
+  splitPatterns,
+  unconstrainedIncludePatterns,
+} from "../stores/exclusionPreview";
 import { useSourcesStore } from "../stores/sources";
 import type { SourceDto } from "../ipc/types";
 
@@ -101,12 +105,10 @@ onMounted(async () => {
   await Promise.all([sources.refresh(), accounts.refresh()]);
 });
 
-function splitPatterns(text: string): string[] {
-  return text
-    .split(/[\n,]/)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0);
-}
+// The include rules in the open editor that stop the scanner from pruning
+// excluded folders, recomputed AS THE USER TYPES (the preview walk itself only
+// re-runs on blur, but the guidance should not wait for it).
+const unconstrainedIncludes = computed(() => unconstrainedIncludePatterns(editIncludeText.value));
 
 function openWizard(): void {
   void wizard.value?.start();
@@ -534,6 +536,26 @@ async function confirmRevealAck(sourceId: string): Promise<void> {
               @blur="refreshEditPreview"
             />
           </label>
+          <!-- An include rule the scanner cannot bound to a fixed depth forces
+               it into every excluded folder, so the walk stops being prunable. -->
+          <div
+            v-if="unconstrainedIncludes.length > 0"
+            class="rounded-lg border border-amber-400 bg-amber-50 p-3 text-xs text-amber-800 dark:border-amber-700 dark:bg-amber-950/40 dark:text-amber-200"
+            data-testid="include-pattern-warning"
+            role="status"
+          >
+            <p class="font-medium">
+              {{ t("settings.addSource.includeWarning.title") }}
+            </p>
+            <ul class="mt-1 list-disc space-y-0.5 pl-5 font-mono break-all">
+              <li v-for="pattern in unconstrainedIncludes" :key="pattern">
+                {{ pattern }}
+              </li>
+            </ul>
+            <p class="mt-2">
+              {{ t("settings.addSource.includeWarning.hint") }}
+            </p>
+          </div>
           <label class="block space-y-1 text-sm">
             <span class="text-zinc-600 dark:text-zinc-400">{{
               t("settings.addSource.excludePatternsLabel")

ui/src/locales/en-US.json

@@ -191,6 +191,10 @@
       "respectGitignoreLabel": "Respect .gitignore files",
       "includePatternsLabel": "Include patterns",
       "excludePatternsLabel": "Exclude patterns",
+      "includeWarning": {
+        "title": "These include patterns slow scanning:",
+        "hint": "Patterns without a leading / (or containing **) force the scanner to search inside every excluded folder such as node_modules. Anchor them to fixed depths instead, e.g. /*/.env, /path/to/.env, or /path/*/deploy/.env."
+      },
       "placeholderPolicyLabel": "Back up OneDrive cloud-only files",
       "placeholderPolicyCaption": "Applies to OneDrive / cloud-only placeholder files on Windows (harmless elsewhere). When on, Driven downloads and backs up files that are stored only in the cloud.",
       "preview": {

ui/src/stores/exclusionPreview.ts

@@ -97,13 +97,37 @@ export function anchoredPatternForPath(rel: string, isDir: boolean): string | nu
 
 /** Split a patterns textarea into the glob list the IPC layer takes. Mirrors the
  *  `splitPatterns` both editors already use (newline OR comma separated). */
-function splitPatterns(text: string): string[] {
+export function splitPatterns(text: string): string[] {
   return text
     .split(/[\n,]/)
     .map((p) => p.trim())
     .filter((p) => p.length > 0);
 }
 
+/** Would this include pattern stop the scanner from PRUNING excluded folders?
+ *
+ * The walker skips descending into an excluded directory only when it can prove
+ * no include pattern could ever re-include something below it. That proof needs
+ * a pattern that is anchored to the source root AND bounded in depth, like
+ * `/repo/.env` or a leading-slash pattern whose wildcards each cover a single
+ * segment - those can only match at a known depth, so `node_modules` can be
+ * skipped outright. A relative pattern (`.env`, `blah/.env`) matches at ANY
+ * depth, and one containing a double-star spans any number of levels, so either
+ * forces the walker to descend into every excluded directory just in case -
+ * which is what makes a scan crawl.
+ */
+export function isUnconstrainedIncludePattern(pattern: string): boolean {
+  const trimmed = pattern.trim();
+  if (trimmed === "") return false;
+  return !trimmed.startsWith("/") || trimmed.includes("**");
+}
+
+/** The include patterns in a textarea's raw text that defeat directory pruning,
+ *  in the order the user typed them. Empty when the rules are all prune-safe. */
+export function unconstrainedIncludePatterns(text: string): string[] {
+  return splitPatterns(text).filter(isUnconstrainedIncludePattern);
+}
+
 /** Append `pattern` as a NEW LINE to a patterns textarea's text, skipping the
  * append when the exact pattern is already present (clicking "-" twice on the
  * same row must not stack duplicate rules against the source's 256-pattern cap).