grepmax 0.16.0 → 0.16.2

package/dist/commands/search.js

@@ -368,7 +368,8 @@ exports.search = new commander_1.Command("search")
     .option("--skeleton", "Show code skeleton for matching files instead of snippets", false)
     .option("--root <dir>", "Search a different project directory")
     .option("--file <name>", "Filter to files matching this name (e.g. 'syncer.ts')")
-    .option("--exclude <prefix>", "Exclude files under this path prefix (e.g. 'tests/')")
+    .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable; comma-separated also accepted)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable; e.g. 'tests/')", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--lang <ext>", "Filter by file extension (e.g. 'ts', 'py')")
     .option("--role <role>", "Filter by role: ORCHESTRATION, DEFINITION, IMPLEMENTATION")
     .option("--symbol", "Append call graph after search results", false)
@@ -388,7 +389,7 @@ Examples:
   gmax "handler" --name "handle.*" --exclude tests/
 `)
     .action((pattern, exec_path, _options, cmd) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7, _8, _9;
     const options = cmd.optsWithGlobals();
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
@@ -496,9 +497,16 @@ Examples:
         // Propagate project root to worker processes
         process.env.GMAX_PROJECT_ROOT = projectRoot;
         // Check if project is registered
-        const checkRoot = options.root
-            ? (_c = (0, project_root_1.findProjectRoot)(path.resolve(options.root))) !== null && _c !== void 0 ? _c : path.resolve(options.root)
-            : projectRoot;
+        let checkRoot;
+        if (options.root) {
+            const resolved = (0, project_registry_1.resolveRootOrExit)(options.root);
+            if (resolved === null)
+                return;
+            checkRoot = (_c = (0, project_root_1.findProjectRoot)(resolved)) !== null && _c !== void 0 ? _c : resolved;
+        }
+        else {
+            checkRoot = projectRoot;
+        }
         const project = (0, project_registry_1.getProject)(checkRoot);
         if (!project) {
             console.error(`This project hasn't been added to gmax yet.\n\nRun: gmax add ${checkRoot}\n`);
@@ -509,25 +517,40 @@ Examples:
             console.warn("This project is still being indexed. Results may be incomplete.\n");
         }
         // Compute effective paths + filters early — both the daemon-mediated
-        // and in-process search paths need them.
-        const effectiveRoot = options.root
-            ? (_d = (0, project_root_1.findProjectRoot)(path.resolve(options.root))) !== null && _d !== void 0 ? _d : path.resolve(options.root)
-            : projectRoot;
-        const searchPathPrefix = exec_path
-            ? path.resolve(exec_path)
-            : effectiveRoot;
-        const pathFilter = searchPathPrefix.endsWith("/")
-            ? searchPathPrefix
-            : `${searchPathPrefix}/`;
+        // and in-process search paths need them. Reuse the resolved checkRoot
+        // so --root <name> only resolves once per invocation.
+        const effectiveRoot = checkRoot;
+        // --in / --exclude / [path positional] composition. --in wins over the
+        // positional [path] when both are given (positional was the older
+        // shape; --in is canonical going forward).
+        if (exec_path && options.in && options.in.length > 0) {
+            console.warn("Warning: --in overrides positional [path]; using --in.");
+        }
+        const { resolveScope } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));
+        const scope = resolveScope({
+            projectRoot: effectiveRoot,
+            in: options.in,
+            exclude: options.exclude,
+        });
+        const pathFilter = options.in && options.in.length > 0
+            ? scope.pathPrefix
+            : exec_path
+                ? (() => {
+                    const p = path.resolve(exec_path);
+                    return p.endsWith("/") ? p : `${p}/`;
+                })()
+                : scope.pathPrefix;
         const searchFilters = {};
         if (options.file)
             searchFilters.file = options.file;
-        if (options.exclude)
-            searchFilters.exclude = options.exclude;
         if (options.lang)
             searchFilters.language = options.lang;
         if (options.role)
             searchFilters.role = options.role;
+        if (scope.inPrefixes.length > 0)
+            searchFilters.inPrefixes = scope.inPrefixes;
+        if (scope.excludePrefixes.length > 0)
+            searchFilters.excludePrefixes = scope.excludePrefixes;
         // Daemon-mediated search: ships query+args over IPC, daemon runs the
         // hybrid+rerank against its already-warm VectorDB and worker pool.
         // Drops cold-start cost (~17s wall, 6GB RAM in the CLI) to <1s. Falls
@@ -562,7 +585,7 @@ Examples:
                         precomputedGraph = resp.graph;
                     }
                     else if (process.env.GMAX_DEBUG === "1") {
-                        console.error(`[search] daemon path unavailable: ${(_e = resp.error) !== null && _e !== void 0 ? _e : "unknown"}`);
+                        console.error(`[search] daemon path unavailable: ${(_d = resp.error) !== null && _d !== void 0 ? _d : "unknown"}`);
                     }
                 }
             }
@@ -637,7 +660,7 @@ Examples:
                 }
             }
             // Ensure a watcher is running for live reindexing
-            if (!process.env.VITEST && !((_f = process.env.NODE_ENV) === null || _f === void 0 ? void 0 : _f.includes("test"))) {
+            if (!process.env.VITEST && !((_e = process.env.NODE_ENV) === null || _e === void 0 ? void 0 : _e.includes("test"))) {
                 const { launchWatcher } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/watcher-launcher")));
                 const launched = yield launchWatcher(projectRoot);
                 if (!launched.ok && launched.reason === "spawn-failed") {
@@ -645,9 +668,11 @@ Examples:
                 }
             }
             const searcher = new searcher_1.Searcher(vectorDb);
-            searchResult = yield searcher.search(pattern, parseInt(options.m, 10), { rerank: true, explain: options.explain }, Object.keys(searchFilters).length > 0 ? searchFilters : undefined, pathFilter);
+            searchResult = yield searcher.search(pattern, parseInt(options.m, 10), { rerank: true, explain: options.explain }, Object.keys(searchFilters).length > 0
+                ? searchFilters
+                : undefined, pathFilter);
         } // end if (!searchResult) — in-process fallback
-        if (!options.agent && ((_g = searchResult.warnings) === null || _g === void 0 ? void 0 : _g.length)) {
+        if (!options.agent && ((_f = searchResult.warnings) === null || _f === void 0 ? void 0 : _f.length)) {
             for (const w of searchResult.warnings) {
                 console.warn(`Warning: ${w}`);
             }
@@ -664,7 +689,7 @@ Examples:
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_11) {
+            catch (_10) {
                 // Invalid regex — skip
             }
         }
@@ -690,16 +715,16 @@ Examples:
                 // In agent mode, print imports header per file
                 const seenImportFiles = new Set();
                 for (const r of filteredData) {
-                    const absP = (_k = (_h = r.path) !== null && _h !== void 0 ? _h : (_j = r.metadata) === null || _j === void 0 ? void 0 : _j.path) !== null && _k !== void 0 ? _k : "";
+                    const absP = (_j = (_g = r.path) !== null && _g !== void 0 ? _g : (_h = r.metadata) === null || _h === void 0 ? void 0 : _h.path) !== null && _j !== void 0 ? _j : "";
                     const relPath = absP.startsWith(effectiveRoot)
                         ? absP.slice(effectiveRoot.length + 1)
                         : absP;
-                    const startLine = Math.max(1, ((_p = (_m = (_l = r.startLine) !== null && _l !== void 0 ? _l : r.start_line) !== null && _m !== void 0 ? _m : (_o = r.generated_metadata) === null || _o === void 0 ? void 0 : _o.start_line) !== null && _p !== void 0 ? _p : 0) + 1);
+                    const startLine = Math.max(1, ((_o = (_l = (_k = r.startLine) !== null && _k !== void 0 ? _k : r.start_line) !== null && _l !== void 0 ? _l : (_m = r.generated_metadata) === null || _m === void 0 ? void 0 : _m.start_line) !== null && _o !== void 0 ? _o : 0) + 1);
                     const defs = Array.isArray(r.defined_symbols)
                         ? r.defined_symbols
                         : [];
                     const symbol = defs[0] || "";
-                    const role = ((_q = r.role) !== null && _q !== void 0 ? _q : "")
+                    const role = ((_p = r.role) !== null && _p !== void 0 ? _p : "")
                         .slice(0, 4)
                         .toUpperCase();
                     let hint = "";
@@ -708,7 +733,7 @@ Examples:
                     }
                     else {
                         // Extract first meaningful signature line from content
-                        const raw = (_s = (_r = r.content) !== null && _r !== void 0 ? _r : r.text) !== null && _s !== void 0 ? _s : "";
+                        const raw = (_r = (_q = r.content) !== null && _q !== void 0 ? _q : r.text) !== null && _r !== void 0 ? _r : "";
                         const lines = raw.split("\n");
                         for (const line of lines) {
                             const trimmed = line.trim();
@@ -743,10 +768,12 @@ Examples:
                     }
                     const sym = symbol ? ` ${symbol}` : "";
                     const rl = role ? ` [${role}]` : "";
+                    const score = r.score;
+                    const scoreCol = typeof score === "number" ? `\ts=${score.toFixed(3)}` : "";
                     const explainSuffix = options.explain && r.scoreBreakdown
                         ? `\texplain:rerank=${r.scoreBreakdown.rerank.toFixed(3)},fused=${r.scoreBreakdown.fused.toFixed(3)},boost=${r.scoreBreakdown.boost.toFixed(2)}x,score=${r.scoreBreakdown.normalized.toFixed(3)}`
                         : "";
-                    console.log(`${relPath}:${startLine}${sym}${rl}${hint}${explainSuffix}`);
+                    console.log(`${relPath}:${startLine}${scoreCol}${sym}${rl}${hint}${explainSuffix}`);
                 }
             }
             // Agent trace (compact)
@@ -778,7 +805,7 @@ Examples:
                         }
                     }
                 }
-                catch (_12) { }
+                catch (_11) { }
             }
             return;
         }
@@ -810,9 +837,9 @@ Examples:
             let shown = 0;
             console.log(resultCountHeader(filteredData, parseInt(options.m, 10)));
             for (const r of filteredData) {
-                const absP = (_v = (_t = r.path) !== null && _t !== void 0 ? _t : (_u = r.metadata) === null || _u === void 0 ? void 0 : _u.path) !== null && _v !== void 0 ? _v : "";
-                const startLine = (_z = (_x = (_w = r.startLine) !== null && _w !== void 0 ? _w : r.start_line) !== null && _x !== void 0 ? _x : (_y = r.generated_metadata) === null || _y === void 0 ? void 0 : _y.start_line) !== null && _z !== void 0 ? _z : 0;
-                const endLine = (_3 = (_1 = (_0 = r.endLine) !== null && _0 !== void 0 ? _0 : r.end_line) !== null && _1 !== void 0 ? _1 : (_2 = r.generated_metadata) === null || _2 === void 0 ? void 0 : _2.end_line) !== null && _3 !== void 0 ? _3 : startLine;
+                const absP = (_u = (_s = r.path) !== null && _s !== void 0 ? _s : (_t = r.metadata) === null || _t === void 0 ? void 0 : _t.path) !== null && _u !== void 0 ? _u : "";
+                const startLine = (_y = (_w = (_v = r.startLine) !== null && _v !== void 0 ? _v : r.start_line) !== null && _w !== void 0 ? _w : (_x = r.generated_metadata) === null || _x === void 0 ? void 0 : _x.start_line) !== null && _y !== void 0 ? _y : 0;
+                const endLine = (_2 = (_0 = (_z = r.endLine) !== null && _z !== void 0 ? _z : r.end_line) !== null && _0 !== void 0 ? _0 : (_1 = r.generated_metadata) === null || _1 === void 0 ? void 0 : _1.end_line) !== null && _2 !== void 0 ? _2 : startLine;
                 const relPath = absP.startsWith(projectRoot)
                     ? absP.slice(projectRoot.length + 1)
                     : absP;
@@ -845,7 +872,7 @@ Examples:
                     tokensUsed += blobTokens;
                     shown++;
                 }
-                catch (_13) {
+                catch (_12) {
                     console.log(`\n--- ${relPath} (file not readable) ---`);
                     shown++;
                 }
@@ -862,7 +889,7 @@ Examples:
         if (options.imports) {
             const seenFiles = new Set();
             for (const r of filteredData) {
-                const absP = (_6 = (_4 = r.path) !== null && _4 !== void 0 ? _4 : (_5 = r.metadata) === null || _5 === void 0 ? void 0 : _5.path) !== null && _6 !== void 0 ? _6 : "";
+                const absP = (_5 = (_3 = r.path) !== null && _3 !== void 0 ? _3 : (_4 = r.metadata) === null || _4 === void 0 ? void 0 : _4.path) !== null && _5 !== void 0 ? _5 : "";
                 if (absP && !seenFiles.has(absP)) {
                     seenFiles.add(absP);
                     const imports = getImportsForFile(absP);
@@ -889,7 +916,7 @@ Examples:
                 for (const r of filteredData) {
                     const b = r.scoreBreakdown;
                     if (b) {
-                        const absP = (_9 = (_7 = r.path) !== null && _7 !== void 0 ? _7 : (_8 = r.metadata) === null || _8 === void 0 ? void 0 : _8.path) !== null && _9 !== void 0 ? _9 : "";
+                        const absP = (_8 = (_6 = r.path) !== null && _6 !== void 0 ? _6 : (_7 = r.metadata) === null || _7 === void 0 ? void 0 : _7.path) !== null && _8 !== void 0 ? _8 : "";
                         const relPath = absP.startsWith(projectRoot)
                             ? absP.slice(projectRoot.length + 1)
                             : absP;
@@ -951,7 +978,7 @@ Examples:
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_14) {
+            catch (_13) {
                 // Trace failed — skip silently
             }
         }
@@ -971,13 +998,13 @@ Examples:
                 source: "cli",
                 tool: "search",
                 query: pattern,
-                project: (_10 = (0, project_root_1.findProjectRoot)(root)) !== null && _10 !== void 0 ? _10 : root,
+                project: (_9 = (0, project_root_1.findProjectRoot)(root)) !== null && _9 !== void 0 ? _9 : root,
                 results: _searchResultCount,
                 ms: Date.now() - _searchStartMs,
                 error: _searchError,
             });
         }
-        catch (_15) { }
+        catch (_14) { }
         if (vectorDb) {
             try {
                 yield vectorDb.close();

package/dist/commands/similar.js

@@ -48,6 +48,7 @@ const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
 const filter_builder_1 = require("../lib/utils/filter-builder");
 const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const arrow_1 = require("../lib/utils/arrow");
 exports.similar = new commander_1.Command("similar")
@@ -56,6 +57,8 @@ exports.similar = new commander_1.Command("similar")
     .option("-m, --max-count <n>", "Max results (default 5)", "5")
     .option("--threshold <score>", "Min similarity 0-1 (default 0)")
     .option("--root <dir>", "Project root directory")
+    .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
     .action((target, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b, _c, _d, _e, _f, _g, _h, _j;
@@ -63,7 +66,9 @@ exports.similar = new commander_1.Command("similar")
     const threshold = Number.parseFloat(opts.threshold || "0") || 0;
     let vectorDb = null;
     try {
-        const root = opts.root ? path.resolve(opts.root) : process.cwd();
+        const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
+        if (root === null)
+            return;
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
@@ -106,7 +111,13 @@ exports.similar = new commander_1.Command("similar")
             return;
         }
         // Vector search using the source chunk's embedding
-        const pathScope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(projectRoot)}/%'`;
+        const { resolveScope, buildScopeWhere } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));
+        const scope = resolveScope({
+            projectRoot,
+            in: opts.in,
+            exclude: opts.exclude,
+        });
+        const pathScope = buildScopeWhere(scope);
         const results = yield table
             .vectorSearch(sourceVector)
             .select([

package/dist/commands/skeleton.js

@@ -61,7 +61,6 @@ const setup_helpers_1 = require("../lib/setup/setup-helpers");
 const retriever_1 = require("../lib/skeleton/retriever");
 const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
 const vector_db_1 = require("../lib/store/vector-db");
-const file_utils_1 = require("../lib/utils/file-utils");
 const exit_1 = require("../lib/utils/exit");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
@@ -156,27 +155,18 @@ Examples:
         };
         // Determine mode based on target
         const resolvedTarget = path.resolve(target);
-        // Directory mode
+        // Directory mode is unsupported. Auto-picking files from a directory
+        // was confusingly magical (and on '.' it fell through to the resolver
+        // path and skeletonized .gitignore). Refuse and point at the file form.
         if (fs.existsSync(resolvedTarget) &&
             fs.statSync(resolvedTarget).isDirectory()) {
-            const entries = fs.readdirSync(resolvedTarget, {
-                withFileTypes: true,
-            });
-            const files = entries
-                .filter((e) => e.isFile() &&
-                (0, file_utils_1.isIndexableFile)(path.join(resolvedTarget, e.name)))
-                .map((e) => path.join(resolvedTarget, e.name))
-                .slice(0, Number.parseInt(options.limit, 10));
-            if (files.length === 0) {
-                console.error(`No indexable files in ${target}`);
-                process.exitCode = 1;
-                return;
-            }
-            for (const filePath of files) {
-                const content = fs.readFileSync(filePath, "utf-8");
-                const result = yield skeletonizer.skeletonizeFile(filePath, content, skeletonOpts);
-                outputResult(result, options);
-            }
+            console.error([
+                "skeleton expects a file or symbol, not a directory.",
+                "Try:",
+                "  gmax skeleton src/foo.ts        # one file's structure",
+                '  gmax search "<topic>" --agent   # find relevant files first',
+            ].join("\n"));
+            process.exitCode = 1;
             return;
         }
         // Batch mode (comma-separated)

package/dist/commands/symbols.js

@@ -48,6 +48,7 @@ const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
+const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const style = {
     bold: (s) => `\x1b[1m${s}\x1b[22m`,
@@ -174,7 +175,9 @@ exports.symbols = new commander_1.Command("symbols")
     .option("--agent", "Compact output for AI agents", false)
     .action((pattern, cmd) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b;
-    const root = cmd.root ? path.resolve(cmd.root) : process.cwd();
+    const root = (0, project_registry_1.resolveRootOrExit)(cmd.root);
+    if (root === null)
+        return;
     const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
     const limit = Number.parseInt(cmd.limit, 10);
     // Auto-scope to project root; --path narrows further within it

package/dist/commands/test-find.js

@@ -43,24 +43,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.testFind = void 0;
-const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const impact_1 = require("../lib/graph/impact");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 exports.testFind = new commander_1.Command("test")
     .description("Find tests that exercise a symbol or file")
     .argument("<target>", "Symbol name or file path")
     .option("-d, --depth <n>", "Caller traversal depth (default 1, max 3)", "1")
     .option("--root <dir>", "Project root directory")
+    .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
     .action((target, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
     let vectorDb = null;
     try {
-        const root = opts.root ? path.resolve(opts.root) : process.cwd();
+        const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
+        if (root === null)
+            return;
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
@@ -72,7 +76,16 @@ exports.testFind = new commander_1.Command("test")
             process.exitCode = 1;
             return;
         }
-        const tests = yield (0, impact_1.findTests)(symbols, vectorDb, projectRoot, depth);
+        const { resolveScope } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));
+        const scope = resolveScope({
+            projectRoot,
+            in: opts.in,
+            exclude: opts.exclude,
+        });
+        const queryRoot = opts.in && opts.in.length > 0
+            ? scope.pathPrefix.replace(/\/$/, "")
+            : projectRoot;
+        const tests = yield (0, impact_1.findTests)(symbols, vectorDb, queryRoot, depth, scope.excludePrefixes);
         if (tests.length === 0) {
             console.log(`No tests found for ${target}.`);
             return;

package/dist/commands/trace.js

@@ -43,12 +43,12 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trace = void 0;
-const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const formatter_1 = require("../lib/output/formatter");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
+const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 function formatTraceAgent(graph, projectRoot) {
     if (!graph.center)
@@ -78,17 +78,27 @@ exports.trace = new commander_1.Command("trace")
     .argument("<symbol>", "The symbol to trace")
     .option("-d, --depth <n>", "Caller traversal depth (default 1, max 3)", "1")
     .option("--root <dir>", "Project root directory")
+    .option("--in <subpath>", "Restrict to a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
+    .option("--exclude <subpath>", "Exclude a sub-path of the project (repeatable)", (value, prev) => (prev ? [...prev, value] : [value]))
     .option("--agent", "Compact output for AI agents", false)
     .action((symbol, opts) => __awaiter(void 0, void 0, void 0, function* () {
     var _a;
     const depth = Math.min(Math.max(Number.parseInt(opts.depth || "1", 10), 1), 3);
-    const root = opts.root ? path.resolve(opts.root) : process.cwd();
+    const root = (0, project_registry_1.resolveRootOrExit)(opts.root);
+    if (root === null)
+        return;
     let vectorDb = null;
     try {
         const projectRoot = (_a = (0, project_root_1.findProjectRoot)(root)) !== null && _a !== void 0 ? _a : root;
         const paths = (0, project_root_1.ensureProjectPaths)(projectRoot);
         vectorDb = new vector_db_1.VectorDB(paths.lancedbDir);
-        const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, projectRoot);
+        const { resolveScope } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/scope-filter")));
+        const scope = resolveScope({
+            projectRoot,
+            in: opts.in,
+            exclude: opts.exclude,
+        });
+        const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, scope.pathPrefix, scope.excludePrefixes);
         const graph = yield graphBuilder.buildGraphMultiHop(symbol, depth);
         if (opts.agent) {
             console.log(formatTraceAgent(graph, projectRoot));

package/dist/lib/daemon/daemon.js

@@ -397,8 +397,22 @@ class Daemon {
                 },
             });
             this.processors.set(root, processor);
-            // Subscribe with @parcel/watcher — native backend, no polling
-            yield this.subscribeWatcher(root, processor);
+            // Subscribe with @parcel/watcher — native backend, no polling.
+            // If the kernel refuses (e.g. FSEvents slots stuck after a prior kill -9
+            // — see docs/known-limitations.md), fall straight through to poll mode.
+            // The retry/backoff path inside recoverWatcher is for transient overflows,
+            // not hard kernel-level subscribe failures, so we skip it on startup by
+            // priming failCount past MAX before invoking it.
+            try {
+                yield this.subscribeWatcher(root, processor);
+            }
+            catch (err) {
+                const name = path.basename(root);
+                console.error(`[daemon:${name}] Subscribe failed at startup (${err instanceof Error ? err.message : err}) — switching to poll mode`);
+                this.watcherFailCount.set(root, 1000); // > MAX_WATCHER_RETRIES
+                this.lastOverflowMs.set(root, Date.now());
+                this.recoverWatcher(root, processor);
+            }
             (0, watcher_store_1.registerWatcher)({
                 pid: process.pid,
                 projectRoot: root,

package/dist/lib/daemon/ipc-handler.js

@@ -135,6 +135,10 @@ function handleCommand(daemon, cmd, conn) {
                     try {
                         const limitRaw = typeof cmd.limit === "number" ? cmd.limit : 10;
                         const skeletonLimitRaw = typeof cmd.skeletonLimit === "number" ? cmd.skeletonLimit : undefined;
+                        // Accept both the legacy single-string `exclude` and the new
+                        // `excludePrefixes`/`inPrefixes` arrays (--in/--exclude on the CLI).
+                        // Daemon may outlive a CLI restart, so keep both wire shapes for
+                        // one release; drop the single-string form in v0.17.x.
                         const filters = cmd.filters && typeof cmd.filters === "object" && !Array.isArray(cmd.filters)
                             ? cmd.filters
                             : undefined;

package/dist/lib/graph/graph-builder.js

@@ -12,15 +12,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphBuilder = void 0;
 const filter_builder_1 = require("../utils/filter-builder");
 class GraphBuilder {
-    constructor(db, pathPrefix) {
+    constructor(db, pathPrefix, excludePrefixes) {
         this.db = db;
         // Normalize to ensure trailing slash for LIKE queries
         this.pathPrefix = pathPrefix ? (pathPrefix.endsWith("/") ? pathPrefix : `${pathPrefix}/`) : undefined;
+        this.excludePrefixes = (excludePrefixes !== null && excludePrefixes !== void 0 ? excludePrefixes : []).map((p) => p.endsWith("/") ? p : `${p}/`);
     }
     scopeWhere(condition) {
-        if (!this.pathPrefix)
-            return condition;
-        return `${condition} AND path LIKE '${(0, filter_builder_1.escapeSqlString)(this.pathPrefix)}%'`;
+        let result = condition;
+        if (this.pathPrefix) {
+            result = `${result} AND path LIKE '${(0, filter_builder_1.escapeSqlString)(this.pathPrefix)}%'`;
+        }
+        for (const ex of this.excludePrefixes) {
+            result = `${result} AND path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(ex)}%'`;
+        }
+        return result;
     }
     /**
      * Find all chunks that call the given symbol.

package/dist/lib/graph/impact.js

@@ -57,17 +57,22 @@ function resolveTargetSymbols(target, vectorDb, projectRoot) {
  * This catches cases where tests call methods of a class rather than the class name itself
  * (e.g., Swift tests call `handleNotification()` rather than referencing `DeepLinkRouter`).
  */
-function expandFileSymbols(symbols, vectorDb, projectRoot) {
+function expandFileSymbols(symbols, vectorDb, projectRoot, excludePrefixes) {
     return __awaiter(this, void 0, void 0, function* () {
         if (symbols.length !== 1)
             return symbols;
         const table = yield vectorDb.ensureTable();
         const prefix = projectRoot.endsWith("/") ? projectRoot : `${projectRoot}/`;
+        let where = `array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbols[0])}') AND path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`;
+        for (const ex of excludePrefixes !== null && excludePrefixes !== void 0 ? excludePrefixes : []) {
+            const exNorm = ex.endsWith("/") ? ex : `${ex}/`;
+            where += ` AND path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(exNorm)}%'`;
+        }
         // Find the file that defines this symbol
         const defRows = yield table
             .query()
             .select(["path"])
-            .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbols[0])}') AND path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+            .where(where)
             .limit(1)
             .toArray();
         if (defRows.length === 0)
@@ -92,11 +97,11 @@ function expandFileSymbols(symbols, vectorDb, projectRoot) {
  * Find test files that exercise a set of symbols, using reverse call graph traversal.
  */
 function findTests(symbols_1, vectorDb_1, projectRoot_1) {
-    return __awaiter(this, arguments, void 0, function* (symbols, vectorDb, projectRoot, depth = 1) {
-        const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, projectRoot);
+    return __awaiter(this, arguments, void 0, function* (symbols, vectorDb, projectRoot, depth = 1, excludePrefixes) {
+        const graphBuilder = new graph_builder_1.GraphBuilder(vectorDb, projectRoot, excludePrefixes);
         const testHits = new Map(); // key: file+symbol
         // Expand single-symbol targets to include all symbols from the same file
-        const expanded = yield expandFileSymbols(symbols, vectorDb, projectRoot);
+        const expanded = yield expandFileSymbols(symbols, vectorDb, projectRoot, excludePrefixes);
         for (const symbol of expanded) {
             yield walkCallers(symbol, graphBuilder, testHits, 0, depth, new Set());
         }
@@ -133,9 +138,13 @@ function walkCallers(symbol, graphBuilder, testHits, currentHop, maxDepth, visit
  * Returns files sorted by number of shared symbols (descending).
  */
 function findDependents(symbols_1, vectorDb_1, projectRoot_1, excludePaths_1) {
-    return __awaiter(this, arguments, void 0, function* (symbols, vectorDb, projectRoot, excludePaths, limit = 10) {
+    return __awaiter(this, arguments, void 0, function* (symbols, vectorDb, projectRoot, excludePaths, limit = 10, excludePrefixes) {
         const table = yield vectorDb.ensureTable();
-        const pathScope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(projectRoot)}/%'`;
+        let pathScope = `path LIKE '${(0, filter_builder_1.escapeSqlString)(projectRoot)}/%'`;
+        for (const ex of excludePrefixes !== null && excludePrefixes !== void 0 ? excludePrefixes : []) {
+            const exNorm = ex.endsWith("/") ? ex : `${ex}/`;
+            pathScope += ` AND path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(exNorm)}%'`;
+        }
         const counts = new Map();
         for (const sym of symbols) {
             const rows = yield table

package/dist/lib/index/chunker.js

@@ -362,6 +362,14 @@ class TreeSitterChunker {
                 const allowedParents = ["program", "module", "source_file", "class_body", "export_statement"];
                 if (parentType && !allowedParents.includes(parentType))
                     return false;
+                // Exported declarations are part of the API surface, so always index
+                // them regardless of RHS shape. Without this, files whose only export
+                // is `export const typeDefs = gql\`...\`` (template literals, object
+                // literals, or non-PascalCase consts) had no defined_symbols entry
+                // and peek/extract returned "Symbol not found".
+                if (parentType === "export_statement" || parentType === "export_declaration") {
+                    return true;
+                }
                 const text = node.text || "";
                 if (text.includes("=>"))
                     return true;

package/dist/lib/search/searcher.js

@@ -32,6 +32,34 @@ function buildWhereClause(pathPrefix, filters, searchIntent) {
             : excludeFilter;
         parts.push(`path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(absExclude)}%'`);
     }
+    // New array-shape: pre-resolved absolute exclude prefixes from
+    // resolveScope (or daemon IPC). Each becomes its own NOT LIKE clause.
+    const excludePrefixes = filters === null || filters === void 0 ? void 0 : filters.excludePrefixes;
+    if (Array.isArray(excludePrefixes)) {
+        for (const p of excludePrefixes) {
+            if (typeof p === "string" && p) {
+                const norm = (0, filter_builder_1.normalizePath)(p);
+                parts.push(`path NOT LIKE '${(0, filter_builder_1.escapeSqlString)(norm)}%'`);
+            }
+        }
+    }
+    // Multi-`--in` becomes an OR group of LIKE clauses. Single `--in`
+    // collapses into pathPrefix on the resolveScope side, so we don't see
+    // it here.
+    const inPrefixes = filters === null || filters === void 0 ? void 0 : filters.inPrefixes;
+    if (Array.isArray(inPrefixes) && inPrefixes.length > 0) {
+        const clauses = [];
+        for (const p of inPrefixes) {
+            if (typeof p === "string" && p) {
+                const norm = (0, filter_builder_1.normalizePath)(p);
+                clauses.push(`path LIKE '${(0, filter_builder_1.escapeSqlString)(norm)}%'`);
+            }
+        }
+        if (clauses.length === 1)
+            parts.push(clauses[0]);
+        else if (clauses.length > 1)
+            parts.push(`(${clauses.join(" OR ")})`);
+    }
     const langFilter = filters === null || filters === void 0 ? void 0 : filters.language;
     if (typeof langFilter === "string" && langFilter) {
         const ext = langFilter.startsWith(".") ? langFilter : `.${langFilter}`;