amorfo77/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2026-08-12 05:43:18 +00:00
Code Issues Projects Releases Wiki Activity

chore: build typed search errors from structured diagnostic data

Browse Source 
Diagnostics now carry field and raw_value, so the transition guidance
points at those instead of parsing human-readable message text.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
stumpylog
2026-08-11 09:58:49 -07:00
co-authored by Claude Fable 5
parent d8c9d22ea1
commit c86edaa0e8
1 changed files with 1 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/whoosh-compat-transition/SKILL.md
+1
View File
@@ -15,6 +15,7 @@ whoosh-compat (github.com/stumpylog/whoosh-compat; local checkout usually at `..
- **The field surface is a policy decision, not `KNOWN_FIELDS`.** Today's `KNOWN_FIELDS` accepts internal ID fields (`tag_id`, `owner_id`, `viewer_id`, other `*_id`) that are undocumented in `docs/usage.md` and were ruled not user-searchable by the maintainer: exclude them from the `FieldRegistry` (they stay as programmatic permission/filter fields in `build_permission_filter`, which never touches user query text). The registry is built from documented syntax in `docs/usage.md` plus the v2-compat aliases (`type`, `path`, `type_id`-style aliases follow their canonical field's fate). Undocumented-but-working fields (`asn`, `page_count`, `num_notes`, `original_filename`, `checksum`) need an explicit maintainer yes/no; since users type freely, silently dropping one breaks any saved view using it, so a drop must be a visible, documented decision.
- **Analyzer seam:** `FieldSpec.analyzer` binds the live registered tantivy analyzer's `.analyze` (the same Rust analyzer used at index time; language-keyed, so rebuild the registry when `SEARCH_LANGUAGE` changes, on the same trigger as `register_tokenizers`). `pattern_normalizer` is `_tokenizer.ascii_fold`: character-level lowercase+fold only, NEVER stemming.
- **Diagnostics before emit:** `whoosh_compat.parse()` never raises on bad input. Check `ParseResult.diagnostics` and map to `SearchQueryError`/`InvalidDateQuery` (HTTP 400) BEFORE calling `emit()`; also catch the emitter's `UnsupportedQueryError` into a 400. Never carry forward the legacy raw-string fallback (`except Exception: query_str = raw_query`) into the new path; it masks integration bugs.
- **Build typed errors from structured diagnostic data, never by parsing `message`.** Each `Diagnostic` carries `kind`, `startchar`/`endchar`, and `field`/`raw_value`. `InvalidDateQuery(field, value)` and any `InvalidNumberQuery` come straight from `diagnostic.field` and `diagnostic.raw_value`; `message` is human-readable text whose wording can change. For a range that fails on one bound, `raw_value` is the bound that actually failed.
- **`notes` and `custom_fields` are JSON fields** with fixed subpaths (`notes.user`/`notes.note`, `custom_fields.name`/`custom_fields.value`); the registry stays a static, language-keyed singleton, never per-request.
## Mandatory before deleting old code