justintsus-experiment Public
// The search query parser (search/api.ts): an input string to a SearchQuery, or every error in it.// Never throws. Two passes:// 1. lex: split the input into terms as written (quotes, a leading -, a qualifier's quoted value),// so the term limit counts what was typed and quote errors are found where they are;// 2. read each term: a qualifier (key:value), a number (#12) or free text, checked against the// target's table; then duplicates (the same canonical text) are dropped and a second sort: with// another value is a conflict.import type { DateFilter, DateOp, Day, ParseResult, QueryError, QueryErrorCode, RelUnit, SearchQuery, SortValue, StateValue, Target, Term, UserRef,} from "./ast.ts";import { NUMBER_RE, QUALIFIER_RE, termText } from "./serialize.ts";export const MAX_INPUT = 1024;export const MAX_TERMS = 32;const LABEL_MAX = 32;const WS = /\s/;const KEY_COLON = /^[A-Za-z]+(-[A-Za-z]+)*:$/;const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;const SLUG = /^[a-z0-9][a-z0-9-]{0,38}$/;const LABEL = /^[a-z0-9][a-z0-9 ._-]*$/;type Key = "is" | "label" | "no" | "author" | "review-requested" | "sort" | "created" | "updated";// Which qualifiers each list has.const KEYS: Record<Key, readonly Target[]> = { is: ["issues", "pulls"], label: ["issues"], no: ["issues"], author: ["issues", "pulls"], "review-requested": ["pulls"], sort: ["issues", "pulls"], created: ["issues", "pulls"], updated: ["issues", "pulls"],};const NO_NEGATION: ReadonlySet<Key> = new Set(["no", "sort", "created", "updated"]);export const STATES: Record<Target, readonly StateValue[]> = { issues: ["open", "closed"], pulls: ["open", "closed", "merged", "draft"] };export const SORTS: Record<Target, readonly SortValue[]> = { issues: ["created-desc", "created-asc", "updated-desc", "updated-asc", "comments-desc", "comments-asc"], pulls: ["created-desc", "created-asc", "updated-desc", "updated-asc"],};const LIST: Record<Target, string> = { issues: "issues", pulls: "pull requests" };const EXAMPLE: Record<Key, string> = { is: "is:open", label: "label:bug", no: "no:label", author: "author:@me", "review-requested": "review-requested:@me", sort: "sort:updated-desc", created: "created:>=2026-10-01", updated: "updated:<7d",};// --- lexingtype Lexed = | { kind: "error"; start: number; end: number; code: "unterminated_quote" | "unexpected_quote" } // free text in quotes | { kind: "quoted"; start: number; end: number; neg: boolean; value: string } // a bare term (after the -) | { kind: "bare"; start: number; end: number; neg: boolean; text: string } // key:"value" | { kind: "qualifier"; start: number; end: number; neg: boolean; key: string; value: string };const isWs = (c: string) => WS.test(c);function nextWs(s: string, i: number): number { while (i < s.length && !isWs(s[i])) i++; return i;}// The quoted value opening at s[i] ('"'): its text and the index after the closing quote, or null when// it never closes. \" is a quote and \\ a backslash; any other backslash stays.function readQuoted(s: string, i: number): { value: string; end: number } | null { let out = ""; let j = i + 1; while (j < s.length) { const c = s[j]; if (c === "\\" && (s[j + 1] === '"' || s[j + 1] === "\\")) { out += s[j + 1]; j += 2; } else if (c === '"') return { value: out, end: j + 1 }; else { out += c; j++; } } return null;}function lex(s: string): Lexed[] { const out: Lexed[] = []; let i = 0; while (i < s.length) { while (i < s.length && isWs(s[i])) i++; if (i >= s.length) break; const start = i; let neg = false; if (s[i] === "-" && i + 1 < s.length && !isWs(s[i + 1])) { neg = true; i++; } // a quoted value (free text, or a qualifier's when key is set) from s[at] const quoted = (at: number, key: string | null): boolean => { const q = readQuoted(s, at); if (!q) { out.push({ kind: "error", start, end: s.length, code: "unterminated_quote" }); i = s.length; return false; } if (q.end < s.length && !isWs(s[q.end])) { const end = nextWs(s, q.end); out.push({ kind: "error", start, end, code: "unexpected_quote" }); i = end; return true; } out.push(key === null ? { kind: "quoted", start, end: q.end, neg, value: q.value } : { kind: "qualifier", start, end: q.end, neg, key, value: q.value }); i = q.end; return true; }; if (s[i] === '"') { if (!quoted(i, null)) break; continue; } let j = i; while (j < s.length && !isWs(s[j]) && s[j] !== '"') j++; const text = s.slice(i, j); if (j < s.length && s[j] === '"') { if (KEY_COLON.test(text)) { if (!quoted(j, text.slice(0, -1))) break; continue; } const end = nextWs(s, j); out.push({ kind: "error", start, end, code: "unexpected_quote" }); i = end; continue; } out.push({ kind: "bare", start, end: j, neg, text }); i = j; } return out;}// --- valuesfunction dayOf(s: string): Day | null { const m = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/.exec(s); if (!m) return null; const y = Number(m[1]); const mo = Number(m[2]); const d = Number(m[3]); if (y < 1970 || y > 9999 || mo < 1 || mo > 12 || d < 1) return null; const start = Date.UTC(y, mo - 1, d); if (new Date(start).getUTCDate() !== d) return null; return { text: s, start };}export function dateFilterOf(v: string): DateFilter | null { const dots = v.indexOf(".."); if (dots >= 0) { const a = v.slice(0, dots); const b = v.slice(dots + 2); const from = a === "*" ? null : dayOf(a); const to = b === "*" ? null : dayOf(b); if ((a !== "*" && !from) || (b !== "*" && !to) || (!from && !to)) return null; if (from && to && from.start > to.start) return null; return { kind: "range", from, to }; } const m = /^(<=|>=|<|>)(.*)$/s.exec(v); if (m) { const op = m[1] as DateOp; const day = dayOf(m[2]); if (day) return { kind: "cmp", op, day }; const rel = /^([0-9]+)([hdwHDW])$/.exec(m[2]); if (!rel) return null; const n = Number(rel[1]); if (!Number.isSafeInteger(n) || n < 1 || n > 9999) return null; return { kind: "age", op, n, unit: rel[2].toLowerCase() as RelUnit }; } const day = dayOf(v); return day ? { kind: "day", day } : null;}export function labelOf(v: string): string | null { const l = v.trim().toLowerCase().replace(/\s+/g, " "); return l.length <= LABEL_MAX && LABEL.test(l) ? l : null;}function userOf(v: string): UserRef | null { const l = v.toLowerCase(); if (l === "@me") return { kind: "me" }; if (UUID.test(l)) return { kind: "id", id: l }; if (SLUG.test(l)) return { kind: "slug", slug: l }; return null;}// --- termstype Failure = { code: QueryErrorCode; message: string };const fail = (code: QueryErrorCode, message: string): Failure => ({ code, message });function qualifier(target: Target, rawKey: string, value: string, neg: boolean): Term | Failure { const key = rawKey.toLowerCase(); if (!Object.hasOwn(KEYS, key)) { return fail("unknown_qualifier", `${key}: is not something ${LIST[target]} can be searched by. Remove it, or put it in quotes to search for the text.`); } const k = key as Key; if (!KEYS[k].includes(target)) return fail("unsupported_qualifier", `${k}: does not apply to ${LIST[target]}.`); if (value === "") return fail("empty_value", `${k}: needs a value, for example ${EXAMPLE[k]}.`); if (neg && NO_NEGATION.has(k)) return fail("negation_not_allowed", `${k}: cannot be negated. Remove the - before it.`); const lower = value.toLowerCase(); switch (k) { case "is": { const s = STATES[target].find((x) => x === lower); return s ? { kind: "is", neg, value: s } : fail("bad_value", `Use ${or(STATES[target].map((x) => `is:${x}`))} for ${LIST[target]}.`); } case "label": { const l = labelOf(value); return l !== null ? { kind: "label", neg, value: l } : fail("bad_value", `A label is up to ${LABEL_MAX} letters, digits, spaces, dots, dashes or underscores, starting with a letter or digit.`); } case "no": return lower === "label" ? { kind: "no", value: "label" } : fail("bad_value", "Use no:label for issues without labels."); case "author": case "review-requested": { const u = userOf(value); if (!u) return fail("bad_value", `Use ${k}:@me, a user id, or the name of one of the organization's agents.`); return k === "author" ? { kind: "author", neg, user: u } : { kind: "review-requested", neg, user: u }; } case "sort": { const s = SORTS[target].find((x) => x === lower); return s ? { kind: "sort", value: s } : fail("bad_value", `Use ${or(SORTS[target].map((x) => `sort:${x}`))} for ${LIST[target]}.`); } case "created": case "updated": { const f = dateFilterOf(value); return f ? { kind: "date", field: k, filter: f } : fail("bad_date", `Use a day like ${k}:2026-10-01 (also with >, >=, < or <=), a range like ${k}:2026-10-01..2026-10-31, or an age like ${k}:<7d.`); } }}function or(list: readonly string[]): string { return list.length < 2 ? list.join("") : `${list.slice(0, -1).join(", ")} or ${list[list.length - 1]}`;}function termOf(target: Target, t: Exclude<Lexed, { kind: "error" }>): Term | Failure { if (t.kind === "quoted") { return /\S/.test(t.value) ? { kind: "text", neg: t.neg, value: t.value } : fail("empty_value", "These quotes hold no text. Write something between them or remove them."); } if (t.kind === "qualifier") return qualifier(target, t.key, t.value, t.neg); const m = QUALIFIER_RE.exec(t.text); if (m) return qualifier(target, m[0].slice(0, -1), t.text.slice(m[0].length), t.neg); if (NUMBER_RE.test(t.text)) { return t.neg ? fail("negation_not_allowed", "A number cannot be negated. Remove the - before it.") : { kind: "number", value: Number(t.text.slice(1)) }; } return { kind: "text", neg: t.neg, value: t.text };}const LEX_MESSAGE = { unterminated_quote: 'This quote is never closed. Add a " at the end of the phrase.', unexpected_quote: 'A quote starts a phrase or a qualifier\'s value and ends at a space. Add a space next to it, or remove it.',};export function parseQuery(input: string, target: Target): ParseResult { try { return parse(String(input), target === "pulls" ? "pulls" : "issues"); } catch { // not reached: the parser handles every string; a query is data, never an exception const s = String(input ?? ""); return { ok: false, errors: [{ code: "bad_value", message: "This search could not be read. Change it and try again.", start: 0, end: s.length }] }; }}function parse(input: string, target: Target): ParseResult { if (input.length > MAX_INPUT) { return { ok: false, errors: [{ code: "too_long", message: `A search is at most ${MAX_INPUT.toLocaleString("en-US")} characters. Shorten it.`, start: 0, end: input.length }] }; } const lexed = lex(input); if (lexed.length > MAX_TERMS) { return { ok: false, errors: [{ code: "too_many_terms", message: `A search has at most ${MAX_TERMS} terms. Remove some.`, start: lexed[MAX_TERMS].start, end: input.length }] }; } const errors: QueryError[] = []; const terms: Term[] = []; const seen = new Set<string>(); let sort: string | null = null; for (const t of lexed) { if (t.kind === "error") { errors.push({ code: t.code, message: LEX_MESSAGE[t.code], start: t.start, end: t.end }); continue; } const r = termOf(target, t); if ("code" in r) { errors.push({ code: r.code, message: r.message, start: t.start, end: t.end }); continue; } if (r.kind === "sort") { if (sort !== null && sort !== r.value) { errors.push({ code: "conflict", message: `This search is already sorted by ${sort}. Keep one sort: term.`, start: t.start, end: t.end }); continue; } sort = r.value; } const text = termText(r); if (seen.has(text)) continue; seen.add(text); terms.push(r); } if (errors.length) return { ok: false, errors }; const query: SearchQuery = { target, terms }; return { ok: true, query };}