Skip to content

Add path filtering and explain metadata to search APIs#665

Open
fa1k3 wants to merge 3 commits into
tobi:mainfrom
fa1k3:feat/path-filter-score-breakdown-v2
Open

Add path filtering and explain metadata to search APIs#665
fa1k3 wants to merge 3 commits into
tobi:mainfrom
fa1k3:feat/path-filter-score-breakdown-v2

Conversation

@fa1k3
Copy link
Copy Markdown

@fa1k3 fa1k3 commented May 20, 2026

Summary

Adds folder-scoped search filtering and richer score explanation metadata across qmd search APIs.

Changes

  • Add pathPrefix filtering to SDK/MCP/REST search paths and --path/-p to the CLI.
  • Preserve original indexed file paths in documents.original_path and use them for user-facing path filtering/results, while keeping existing normalized path compatibility.
  • Preserve original paths in document lookup, CLI get, and CLI/SDK multi-get as well, so a path returned by search (for example qmd://collection/+Projects/Some Folder/file.md) can be passed back to qmd get, MCP/SDK lookup, and glob multi-get without manually converting to the normalized slug form.
  • Make pathPrefix folder-only, case-sensitive, boundary-safe, and slash-normalized:
    • stack matches stack/...
    • stack does not match stack0/... or stack-monitor/...
    • Stack and stack remain distinct
    • empty string and / behave as no filter
  • Add explain.scoreType and per-result explain.backendSources so callers can distinguish RRF-position scores from rerank-blend scores and see whether a result came from BM25 and/or vector evidence.
  • Harden HTTP /query JSON handling for malformed JSON and invalid pathPrefix / explain types.

Semantics

pathPrefix is intentionally folder-scoped, not file-prefix matching. File-like prefixes such as README.md normalize to a folder prefix and therefore do not match the file itself.

Tests

Latest targeted verification after the original-path roundtrip fix:

  • bun test test/path-filter.test.ts test/score-breakdown.test.ts test/cli.test.ts --timeout 60000 --preload ./src/test-preload.ts — 137 passed
  • npm run test:node -- test/path-filter.test.ts test/score-breakdown.test.ts test/cli.test.ts — 137 passed
  • bun run build
  • npm run test:types

Earlier full-suite verification on this PR branch:

  • npm run test:node -- test/path-filter.test.ts test/score-breakdown.test.ts test/mcp.test.ts — 70 passed
  • npm run test:node — 904 passed
  • npm run test:bun — 904 passed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant