@massa-ai/core 1.2.1

package/dist/services/search/contextual-search-rlm.js

@@ -0,0 +1,260 @@
+/**
+ * ContextualSearchRLM - Optimized Contextual Search Service
+ *
+ * Implementation inspired by parallel search patterns,
+ * adapted for the RLM ecosystem with:
+ *
+ * Features:
+ * - Automatic project indexing with per-projectId namespace
+ * - Hybrid search (vector + keyword) with RRF (Reciprocal Rank Fusion)
+ * - Parallel search across multiple files
+ * - Returns only relevant excerpts with context
+ * - Multi-level intelligent cache
+ * - Integration with existing embedding service
+ *
+ * Architecture:
+ * - Uses PostgreSQL as single backend (vector + keyword + cache)
+ * - Per-projectId namespace for isolation
+ * - Embedding reuse across projects
+ */
+import { glob } from "glob";
+import { FileFilterCache } from "./file-filter-cache.js";
+import { QueryUnderstandingService, } from "./query-understanding.js";
+import { assertParserReadyForIndexing } from "../structural/parser-readiness.js";
+import { runWithIndexLock, _indexProjectInternalImpl, ensureFreshIndexImpl, indexFileImpl, loadGitignoreImpl, checkSearchAdmissionImpl, ensureInitializedImpl, } from "./rlm-indexing.js";
+import { applySynapseStateImpl, correctQueryImpl, buildGraphStreamImpl, } from "./rlm-synapse.js";
+import { searchImpl, fuseResultsImpl, generateScoreExplanationImpl, addContextToResultsImpl, extractPreviewImpl, calculateAvgScoreImpl, filterByPatternsImpl, } from "./rlm-search.js";
+import { clearProjectIndexImpl, getProjectStatsImpl, warmupCacheImpl, getAnalyticsImpl, } from "./rlm-admin.js";
+const globAsync = glob;
+/**
+ * ContextualSearchRLM - Main contextual search service
+ */
+export class ContextualSearchRLM {
+    // NOTE (M14 Phase 3): fields below were `private`. Relaxed to `public`
+    // (modifier dropped) so the extracted delegate modules in rlm-indexing.ts /
+    // rlm-synapse.ts / rlm-search.ts / rlm-admin.ts can read them via the passed
+    // `rlm` parameter. Runtime-identical; type-surface only. See design.md
+    // "Encapsulation decision (accepted cost)".
+    keywordSearch;
+    vectorStore;
+    indexManager;
+    searchCache;
+    analytics;
+    symbolRepo;
+    // Visibility relaxed from `private` so rlm-admin.ts can read via rlm param.
+    fileFilterCache;
+    /** Phase 2: query understanding (LLM rewrite + HyDE). Default-off, silent-degrade. */
+    // Visibility relaxed from `private` so rlm-search.ts can read via rlm param.
+    queryUnderstanding;
+    // Visibility relaxed from `private` so rlm-search.ts (fuseResults) can read.
+    RRF_K = 60; // Constant for Reciprocal Rank Fusion
+    initialized = false;
+    // Per-project mutex to prevent concurrent indexing
+    static indexingLocks = new Map();
+    /**
+     * Optional test/extension seam: pre-resolved dependencies. When provided,
+     * `ensureInitialized` skips the factory calls (which are process-wide
+     * mock.module targets in the full test suite) and uses these instances
+     * directly. Production callers pass nothing and resolve via factories.
+     */
+    injectedDeps;
+    constructor(deps) {
+        this.fileFilterCache = new FileFilterCache();
+        this.queryUnderstanding = new QueryUnderstandingService();
+        this.injectedDeps = deps;
+    }
+    // Delegate-preservation contract: stays an instance method (thin delegate
+    // to the module function) because concurrent-indexing.test.ts:67 and the
+    // characterization test monkey-patch `(inst as any).ensureInitialized` on
+    // the instance; routing through a module-local function would bypass that.
+    // Visibility relaxed from `private` to public-equivalent so rlm-indexing.ts
+    // can dispatch through `rlm.ensureInitialized()` (runtime-identical).
+    async ensureInitialized() {
+        return ensureInitializedImpl(this);
+    }
+    /**
+     * Load and parse .gitignore file (delegates to shared ignore-patterns module)
+     */
+    loadGitignore(projectPath) {
+        return loadGitignoreImpl(projectPath);
+    }
+    /**
+     * Index an entire project
+     *
+     * @param projectPath - Path to the project
+     * @param projectId - Unique project ID (namespace)
+     * @returns Indexing statistics
+     */
+    async indexProject(projectPath, projectId, options = {}) {
+        // This legacy direct indexing path must fail before mutating its queue.
+        await assertParserReadyForIndexing();
+        // `work` lambda captures virtual dispatch through `this` so the test's
+        // `(inst as any)._indexProjectInternal` patch still routes (Challenge #1).
+        return runWithIndexLock(ContextualSearchRLM.indexingLocks, projectId, () => this._indexProjectInternal(projectPath, projectId, options));
+    }
+    // Delegate-preservation contract: stays an instance method (thin delegate
+    // to the module function) because concurrent-indexing.test.ts:181-289 and
+    // the characterization test monkey-patch `(inst as any)._indexProjectInternal`
+    // on the instance; routing through a module-local function would bypass it.
+    async _indexProjectInternal(projectPath, projectId, options = {}) {
+        return _indexProjectInternalImpl(this, projectPath, projectId, options);
+    }
+    /**
+     * Check if index is stale and optionally trigger reindexing
+     */
+    async ensureFreshIndex(projectId, projectPath, options = {}) {
+        return ensureFreshIndexImpl(this, projectId, projectPath, options);
+    }
+    /**
+     * Search admission preflight — two-tier gate run before `search()`.
+     *
+     * Tier 1 (HARD-FAIL): pure metadata-existence check, no projectPath needed.
+     *   Returns `{admitted:false, error}` when the project has no index metadata
+     *   at all. Caller MUST surface the error and NOT call `search()`.
+     *
+     * Tier 2 (WARN): only evaluated when `projectPath` is supplied (the staleness
+     *   check needs it). If metadata exists but `isIndexStale` reports any reason
+     *   (files_changed / path_mismatch / age_threshold), admission still succeeds
+     *   but a `stale` descriptor is attached for the caller to relay as a warning.
+     *   When `projectPath` is absent the stale check is skipped gracefully.
+     */
+    async checkSearchAdmission(projectId, projectPath) {
+        return checkSearchAdmissionImpl(this, projectId, projectPath);
+    }
+    /**
+     * Index a single file, splitting it into semantic chunks
+     *
+     * Uses the smart chunker which is language-aware:
+     * - Markdown: splits by headings with hierarchy context
+     * - JSON: splits by top-level keys
+     * - YAML: splits by document separators or top-level keys
+     * - Code: splits by functions/classes with preceding comments
+     */
+    // Visibility relaxed from `private` so rlm-indexing.ts can dispatch through
+    // `rlm.indexFile()` (runtime-identical; type-additive only).
+    async indexFile(filePath, projectId, projectRoot, centralityMap) {
+        return indexFileImpl(this, filePath, projectId, projectRoot, centralityMap);
+    }
+    /**
+     * Hybrid search (vector + keyword) with projectId filter
+     */
+    async search(query, projectId, options = {}) {
+        return searchImpl(this, query, projectId, options);
+    }
+    /**
+     * Apply session state after the session-independent base result is cached.
+     * Invalid and workspace-mismatched sessions return the exact base array.
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    async applySynapseState(baseResults, query, projectId, sessionId, reportDegradation) {
+        return applySynapseStateImpl(this, baseResults, query, projectId, sessionId, reportDegradation);
+    }
+    /**
+     * Fuzzy-correct each non-stopword query term via the keyword store's
+     * vocabulary. Returns the corrected query string (lowercased, space-joined),
+     * or null when no term corrects to a different word or fuzzyCorrect is
+     * unavailable. Only words of length >= 3 are considered (shorter tokens
+     * can't be reliably corrected).
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    async correctQuery(query) {
+        return correctQueryImpl(this, query);
+    }
+    /**
+     * Phase 7c: build the graph-neighbor RRF stream. BFS depth-2 over outgoing
+     * memory-graph edges; resolved to SearchResults via the memory repository at
+     * a fixed sub-hit score (0.45).
+     *
+     * Id-bridge fix (A3): graph edges connect MEMORY ids, but vector/code-search
+     * results key on chunk ids (e.g. "projectId:path:0"). Seeding BFS with chunk
+     * ids therefore silently omitted the stream for code queries — the primary
+     * use case. We now bridge the two id spaces: collect graph seeds by (a)
+     * trying the raw hit ids (preserves the original behavior for memory search
+     * where memory ids already flow in), AND (b) mapping each code chunk to
+     * memory ids that reference the same filePath/symbol via fullTextSearch.
+     * This makes the graph stream participate for code queries while remaining
+     * a silent-omit no-op when no bridged seeds resolve.
+     *
+     * Degradation (silent-omit): returns [] when the neighbor set is empty, the
+     * graph store throws, or the memory repo returns nothing. The caller only
+     * appends the stream when non-empty, so `resultSets.length` (and thus the
+     * `search:reranked` streamCount) always reflects the real stream count.
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    async buildGraphStream(resultSets, maxResults, projectId, reportDegradation) {
+        return buildGraphStreamImpl(this, resultSets, maxResults, projectId, reportDegradation);
+    }
+    /**
+     * Reciprocal Rank Fusion (RRF) - Combines multiple result lists
+     *
+     * Now includes intelligent boosting:
+     * - Keywords get higher weight when query contains function/class names
+     * - Exact matches in keyword results get additional boost
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    fuseResults(resultSets, query, explainScores = false) {
+        return fuseResultsImpl(this, resultSets, query, explainScores);
+    }
+    /**
+     * Generate detailed score explanation
+     */
+    // Visibility relaxed from `private` so rlm-search.ts (fuseResults) can call via rlm param.
+    generateScoreExplanation(finalScore, rrfScore, vectorScore, keywordScore, vectorRank, keywordRank, combinedRank) {
+        return generateScoreExplanationImpl(finalScore, rrfScore, vectorScore, keywordScore, vectorRank, keywordRank, combinedRank);
+    }
+    /**
+     * Add expanded context to results
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    async addContextToResults(results, _projectId) {
+        return addContextToResultsImpl(this, results, _projectId);
+    }
+    /**
+     * Extract content preview (first lines)
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    extractPreview(content, maxLines = 5) {
+        return extractPreviewImpl(content, maxLines);
+    }
+    /**
+     * Calculate average score
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    calculateAvgScore(results) {
+        return calculateAvgScoreImpl(results);
+    }
+    /**
+     * Filter results by glob patterns
+     */
+    // Visibility relaxed from `private` so rlm-search.ts can call via rlm param.
+    filterByPatterns(results, include, exclude) {
+        return filterByPatternsImpl(results, include, exclude);
+    }
+    /**
+     * Clear project index
+     */
+    async clearProjectIndex(projectId) {
+        return clearProjectIndexImpl(this, projectId);
+    }
+    /**
+     * Get project statistics
+     */
+    async getProjectStats(projectId) {
+        return getProjectStatsImpl(this, projectId);
+    }
+    /**
+     * Warmup cache with common queries
+     *
+     * Pre-caches typical search patterns to improve initial search performance
+     */
+    async warmupCache(projectId, _projectPath, customQueries) {
+        return warmupCacheImpl(this, projectId, _projectPath, customQueries);
+    }
+    /**
+     * Get analytics instance for querying metrics
+     */
+    getAnalytics() {
+        return getAnalyticsImpl(this);
+    }
+}
+//# sourceMappingURL=contextual-search-rlm.js.map

package/dist/services/search/contextual-search-rlm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextual-search-rlm.js","sourceRoot":"","sources":["../../../src/services/search/contextual-search-rlm.ts"],"names":[],"mappings":"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"}

package/dist/services/search/file-filter-cache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * File Filter Cache
+ *
+ * Pre-computes and caches valid file lists based on include/exclude patterns.
+ * This avoids re-applying glob filters on every search, significantly improving
+ * performance when filters are used.
+ *
+ * Benefits:
+ * - 40-60% reduction in file filtering overhead
+ * - Filters applied DURING vector search, not after
+ * - Efficient pattern matching using minimatch
+ */
+export declare class FileFilterCache {
+    private cache;
+    private readonly MAX_CACHE_SIZE;
+    private readonly TTL_MS;
+    /**
+     * Get or compute valid files for a project with given filters
+     */
+    getValidFiles(projectId: string, allProjectFiles: string[], include?: string[], exclude?: string[]): Set<string>;
+    /**
+     * Compute which files match the include/exclude patterns
+     */
+    private computeValidFiles;
+    /**
+     * Generate cache key from project ID and filter patterns
+     */
+    private generateKey;
+    /**
+     * Evict oldest entry when cache is full
+     */
+    private evictOldest;
+    /**
+     * Invalidate cache for a specific project
+     */
+    invalidateProject(projectId: string): number;
+    /**
+     * Clear entire cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        entries: Array<{
+            key: string;
+            fileCount: number;
+            accessCount: number;
+            ageMs: number;
+        }>;
+    };
+}
+//# sourceMappingURL=file-filter-cache.d.ts.map

package/dist/services/search/file-filter-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-filter-cache.d.ts","sourceRoot":"","sources":["../../../src/services/search/file-filter-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAM;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAElC;;OAEG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,GAAG,CAAC,MAAM,CAAC;IAsDd;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAiBnB;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAoB5C;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI;QACV,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,KAAK,CAAC;YACb,GAAG,EAAE,MAAM,CAAC;YACZ,SAAS,EAAE,MAAM,CAAC;YAClB,WAAW,EAAE,MAAM,CAAC;YACpB,KAAK,EAAE,MAAM,CAAC;SACf,CAAC,CAAC;KACJ;CAeF"}

package/dist/services/search/file-filter-cache.js

@@ -0,0 +1,159 @@
+/**
+ * File Filter Cache
+ *
+ * Pre-computes and caches valid file lists based on include/exclude patterns.
+ * This avoids re-applying glob filters on every search, significantly improving
+ * performance when filters are used.
+ *
+ * Benefits:
+ * - 40-60% reduction in file filtering overhead
+ * - Filters applied DURING vector search, not after
+ * - Efficient pattern matching using minimatch
+ */
+import { minimatch } from "minimatch";
+import { logger } from "@massa-ai/shared";
+export class FileFilterCache {
+    cache = new Map();
+    MAX_CACHE_SIZE = 50; // Maximum number of filter combinations to cache
+    TTL_MS = 3600000; // 1 hour
+    /**
+     * Get or compute valid files for a project with given filters
+     */
+    getValidFiles(projectId, allProjectFiles, include, exclude) {
+        const cacheKey = this.generateKey({ projectId, include, exclude });
+        // Check cache
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            const now = Date.now();
+            // Check if expired
+            if (now - cached.createdAt > this.TTL_MS) {
+                this.cache.delete(cacheKey);
+                logger.debug("Filter cache entry expired", { projectId, cacheKey });
+            }
+            else {
+                cached.accessCount++;
+                logger.debug("Filter cache hit", {
+                    projectId,
+                    fileCount: cached.files.size,
+                    accessCount: cached.accessCount,
+                });
+                return new Set(cached.files); // Return copy
+            }
+        }
+        // Cache miss - compute valid files
+        const startTime = performance.now();
+        const validFiles = this.computeValidFiles(allProjectFiles, include, exclude);
+        const duration = performance.now() - startTime;
+        // Store in cache
+        this.cache.set(cacheKey, {
+            files: validFiles,
+            createdAt: Date.now(),
+            accessCount: 1,
+        });
+        // Enforce size limit (LRU-like: remove oldest if over limit)
+        if (this.cache.size > this.MAX_CACHE_SIZE) {
+            this.evictOldest();
+        }
+        logger.debug("Filter cache miss - computed valid files", {
+            projectId,
+            fileCount: validFiles.size,
+            totalFiles: allProjectFiles.length,
+            duration: `${duration.toFixed(2)}ms`,
+        });
+        return new Set(validFiles); // Return copy
+    }
+    /**
+     * Compute which files match the include/exclude patterns
+     */
+    computeValidFiles(allFiles, include, exclude) {
+        const valid = new Set();
+        for (const file of allFiles) {
+            // Apply exclude filters first (blacklist)
+            if (exclude && exclude.length > 0) {
+                const excluded = exclude.some((pattern) => minimatch(file, pattern));
+                if (excluded)
+                    continue;
+            }
+            // Apply include filters (whitelist)
+            if (include && include.length > 0) {
+                const included = include.some((pattern) => minimatch(file, pattern));
+                if (!included)
+                    continue;
+            }
+            valid.add(file);
+        }
+        return valid;
+    }
+    /**
+     * Generate cache key from project ID and filter patterns
+     */
+    generateKey(params) {
+        const parts = [
+            `project:${params.projectId}`,
+            params.include ? `include:${params.include.sort().join(",")}` : "",
+            params.exclude ? `exclude:${params.exclude.sort().join(",")}` : "",
+        ].filter(Boolean);
+        return parts.join("|");
+    }
+    /**
+     * Evict oldest entry when cache is full
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.createdAt < oldestTime) {
+                oldestTime = entry.createdAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            logger.debug("Evicted oldest filter cache entry", { key: oldestKey });
+        }
+    }
+    /**
+     * Invalidate cache for a specific project
+     */
+    invalidateProject(projectId) {
+        let removed = 0;
+        for (const [key, _entry] of this.cache.entries()) {
+            if (key.startsWith(`project:${projectId}|`)) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        if (removed > 0) {
+            logger.info("Invalidated file filter cache for project", {
+                projectId,
+                entriesRemoved: removed,
+            });
+        }
+        return removed;
+    }
+    /**
+     * Clear entire cache
+     */
+    clear() {
+        this.cache.clear();
+        logger.info("File filter cache cleared");
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const entries = Array.from(this.cache.entries()).map(([key, entry]) => ({
+            key,
+            fileCount: entry.files.size,
+            accessCount: entry.accessCount,
+            ageMs: now - entry.createdAt,
+        }));
+        return {
+            size: this.cache.size,
+            maxSize: this.MAX_CACHE_SIZE,
+            entries,
+        };
+    }
+}
+//# sourceMappingURL=file-filter-cache.js.map

package/dist/services/search/file-filter-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-filter-cache.js","sourceRoot":"","sources":["../../../src/services/search/file-filter-cache.ts"],"names":[],"mappings":"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"}

package/dist/services/search/filter-validation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Filter Validation — Wave 5 FR-18 / N16 / AD-W5-012 / AC-15.
+ *
+ * Pure module (no I/O): server-side revalidation of client filter hints
+ * before `filterByPatterns` consumes them.
+ *
+ * Three guarantees:
+ *  1. Cap — `include.length + exclude.length ≤ maxFilterPatterns` (default 32,
+ *     env `MAX_FILTER_PATTERNS`). Exceeding → teaching error (throw).
+ *  2. Glob syntax — each pattern validated via `minimatch.makeRe` try/catch.
+ *     A pattern that throws or returns `false` (no usable regex) → teaching
+ *     error (throw).
+ *  3. Contradiction downgrade — when the SAME pattern appears in both
+ *     `include` and `exclude`, the `exclude` entry is dropped and a
+ *     `filter_downgrades: [{ pattern, reason }]` entry is emitted. This is
+ *     observable (never silent drop both). The `include` entry survives so the
+ *     pattern's files remain in results.
+ *
+ * The caller passes the cleaned (post-downgrade) include/exclude to
+ * `filterByPatterns` and attaches `filter_downgrades` to the response (additive,
+ * only when non-empty).
+ */
+/**
+ * A downgrade record emitted when a contradictory pattern is reconciled.
+ * Observable on the response so the caller can correct its hints.
+ */
+export interface FilterDowngrade {
+    /** The glob pattern that was downgraded. */
+    pattern: string;
+    /** Why it was downgraded (human-readable). */
+    reason: string;
+}
+/**
+ * Result of {@link validateFilters}. The cleaned `include` / `exclude`
+ * arrays are what `filterByPatterns` should consume. `downgrades` is
+ * attached to the response when non-empty.
+ */
+export interface FilterValidationResult {
+    include: string[];
+    exclude: string[];
+    downgrades: FilterDowngrade[];
+}
+/**
+ * Default cap for include.length + exclude.length. Mirror of
+ * `config.filterValidation.maxFilterPatterns` (env `MAX_FILTER_PATTERNS`).
+ * Callers SHOULD pass the config value; this is the fallback when no config
+ * is available (e.g. unit tests).
+ */
+export declare const DEFAULT_MAX_FILTER_PATTERNS = 32;
+/**
+ * Validate and clean client-supplied include/exclude filter patterns.
+ *
+ * @param include  client include patterns (may be undefined/empty)
+ * @param exclude  client exclude patterns (may be undefined/empty)
+ * @param maxFilterPatterns  cap from config.filterValidation.maxFilterPatterns
+ *                           (default {@link DEFAULT_MAX_FILTER_PATTERNS})
+ * @returns cleaned patterns + downgrade records
+ * @throws ToolError (400) when the cap is exceeded or a glob is invalid
+ */
+export declare function validateFilters(include: string[] | undefined, exclude: string[] | undefined, maxFilterPatterns?: number): FilterValidationResult;
+//# sourceMappingURL=filter-validation.d.ts.map

package/dist/services/search/filter-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-validation.d.ts","sourceRoot":"","sources":["../../../src/services/search/filter-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAC7B,iBAAiB,GAAE,MAAoC,GACtD,sBAAsB,CAiDxB"}

package/dist/services/search/filter-validation.js

@@ -0,0 +1,111 @@
+/**
+ * Filter Validation — Wave 5 FR-18 / N16 / AD-W5-012 / AC-15.
+ *
+ * Pure module (no I/O): server-side revalidation of client filter hints
+ * before `filterByPatterns` consumes them.
+ *
+ * Three guarantees:
+ *  1. Cap — `include.length + exclude.length ≤ maxFilterPatterns` (default 32,
+ *     env `MAX_FILTER_PATTERNS`). Exceeding → teaching error (throw).
+ *  2. Glob syntax — each pattern validated via `minimatch.makeRe` try/catch.
+ *     A pattern that throws or returns `false` (no usable regex) → teaching
+ *     error (throw).
+ *  3. Contradiction downgrade — when the SAME pattern appears in both
+ *     `include` and `exclude`, the `exclude` entry is dropped and a
+ *     `filter_downgrades: [{ pattern, reason }]` entry is emitted. This is
+ *     observable (never silent drop both). The `include` entry survives so the
+ *     pattern's files remain in results.
+ *
+ * The caller passes the cleaned (post-downgrade) include/exclude to
+ * `filterByPatterns` and attaches `filter_downgrades` to the response (additive,
+ * only when non-empty).
+ */
+import { minimatch } from "minimatch";
+import { ToolError } from "../../tools/enum-validation.js";
+/**
+ * Default cap for include.length + exclude.length. Mirror of
+ * `config.filterValidation.maxFilterPatterns` (env `MAX_FILTER_PATTERNS`).
+ * Callers SHOULD pass the config value; this is the fallback when no config
+ * is available (e.g. unit tests).
+ */
+export const DEFAULT_MAX_FILTER_PATTERNS = 32;
+/**
+ * Validate and clean client-supplied include/exclude filter patterns.
+ *
+ * @param include  client include patterns (may be undefined/empty)
+ * @param exclude  client exclude patterns (may be undefined/empty)
+ * @param maxFilterPatterns  cap from config.filterValidation.maxFilterPatterns
+ *                           (default {@link DEFAULT_MAX_FILTER_PATTERNS})
+ * @returns cleaned patterns + downgrade records
+ * @throws ToolError (400) when the cap is exceeded or a glob is invalid
+ */
+export function validateFilters(include, exclude, maxFilterPatterns = DEFAULT_MAX_FILTER_PATTERNS) {
+    const inc = include ? [...include] : [];
+    const exc = exclude ? [...exclude] : [];
+    // 1. Cap (FR-18 / AC-15): total pattern count must not exceed the limit.
+    const total = inc.length + exc.length;
+    if (total > maxFilterPatterns) {
+        throw new ToolError(`filter patterns: ${total} patterns exceed the maximum of ${maxFilterPatterns} ` +
+            `(include=${inc.length}, exclude=${exc.length}). ` +
+            `Reduce the number of include/exclude patterns.`);
+    }
+    // 2. Glob syntax validation (FR-18 / AC-15): minimatch.makeRe try/catch.
+    //    minimatch v9 treats unclosed brackets/braces as literals rather than
+    //    throwing, so we also treat a `false` return (no usable regex) as
+    //    invalid. The try/catch is the spec-mandated contract; the `false`
+    //    check catches the empty-pattern / degenerate case.
+    for (const pattern of inc) {
+        assertValidGlob(pattern, "include");
+    }
+    for (const pattern of exc) {
+        assertValidGlob(pattern, "exclude");
+    }
+    // 3. Contradiction downgrade (FR-18 / AD-W5-012 / AC-15): the SAME pattern
+    //    in both include AND exclude. Drop the EXCLUDE entry (never drop both
+    //    silently) and emit a downgrade record so the caller sees it.
+    const downgrades = [];
+    const includeSet = new Set(inc);
+    const cleanedExclude = [];
+    for (const pattern of exc) {
+        if (includeSet.has(pattern)) {
+            downgrades.push({
+                pattern,
+                reason: "pattern appears in both include and exclude; exclude entry dropped (include wins)",
+            });
+        }
+        else {
+            cleanedExclude.push(pattern);
+        }
+    }
+    return {
+        include: inc,
+        exclude: cleanedExclude,
+        downgrades,
+    };
+}
+/**
+ * Assert a single glob pattern is syntactically valid. Uses
+ * `minimatch.makeRe` in a try/catch per the FR-18 hard constraint. A `false`
+ * return (no usable regex — e.g. empty string) is also rejected.
+ *
+ * @throws ToolError (400) with a teaching error naming the array and pattern.
+ */
+function assertValidGlob(pattern, arrayName) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new ToolError(`filter ${arrayName}: empty pattern is not a valid glob. ` +
+            `Provide a non-empty glob string.`);
+    }
+    let re;
+    try {
+        re = minimatch.makeRe(pattern);
+    }
+    catch (err) {
+        throw new ToolError(`filter ${arrayName}: invalid glob "${pattern}" — ` +
+            `${err instanceof Error ? err.message : String(err)}.`);
+    }
+    if (re === false) {
+        throw new ToolError(`filter ${arrayName}: invalid glob "${pattern}" — ` +
+            `minimatch could not compile a regex for this pattern.`);
+    }
+}
+//# sourceMappingURL=filter-validation.js.map