@orz/query 0.0.0-stage → 0.0.0

package/dist/commands.js

@@ -0,0 +1,260 @@
+/**
+ * Slash commands (T-161), the text half. A command is an ordinary draft line
+ * that happens to parse: it lives in the document, deleting the line cancels
+ * it, and typing `/close` by hand is exactly as good as picking it from the
+ * panel — the panel is input assistance, not the carrier. Submitting strips
+ * the recognized lines out of the body and compiles each one to the caller's
+ * own value.
+ *
+ * Everything here is pure so both an editor (highlighting, the panel) and
+ * the caller (button label, submit) read the same verdict, and a server or a
+ * CLI can read a draft without an editor at all.
+ */
+import { BRACE_LIMIT, expandBraces } from "./braces.js";
+import { shellWords } from "./shell-words.js";
+import { didYouMean } from "./suggest.js";
+import { providerOf, suggestionCandidates, valueVerdict, worstVerdict, } from "./values.js";
+const COMMAND_NAME = /^[a-z0-9-]+$/;
+/**
+ * Throws on a name no line could ever spell and on a name given twice, which
+ * would silently shadow the first: both are mistakes in the caller's list,
+ * not in user input. So are a required argument after an optional one and a
+ * rest argument that is not last, since no line could reach them.
+ */
+export function createCommandRegistry(commands) {
+    const byName = new Map();
+    for (const command of commands) {
+        if (!COMMAND_NAME.test(command.name)) {
+            throw new Error(`slash command "${command.name}" must match ${COMMAND_NAME}`);
+        }
+        if (byName.has(command.name)) {
+            throw new Error(`slash command "${command.name}" is defined twice`);
+        }
+        for (const [i, arg] of command.args.entries()) {
+            const next = command.args[i + 1];
+            if (next === undefined)
+                continue;
+            if (arg.optional && !next.optional) {
+                throw new Error(`slash command "${command.name}": required argument "${next.name}" follows optional "${arg.name}"`);
+            }
+            if (arg.rest) {
+                throw new Error(`slash command "${command.name}": only the last argument may take the rest of the line, not "${arg.name}"`);
+            }
+        }
+        byName.set(command.name, command);
+    }
+    return { commands, byName };
+}
+/**
+ * `In Progress` → `in-progress`. Lowercase, whitespace folded to hyphens,
+ * everything a slash command cannot carry dropped: a status named `Won't
+ * fix` still gets a typeable command.
+ */
+export function slugifyCommandName(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/\s+/g, "-")
+        .replace(/[^a-z0-9-]/g, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-|-$/g, "");
+}
+const COMMAND_HEAD = /^\/([a-z0-9-]+)(?:[ \t]|$)/;
+/** A rest argument's remainder, read with no quoting at all. */
+export function rawWord(text, start) {
+    const raw = text.slice(start);
+    return {
+        start,
+        end: text.length,
+        raw,
+        value: raw,
+        segments: [{ start, end: text.length, quoted: "none" }],
+    };
+}
+/**
+ * The words after the command name, one per argument, or null when there
+ * are too few for the required arguments or too many for the command: then
+ * the line is not that command and stays prose, so `/close the door` is a
+ * sentence. An open quote swallows the words after it, so with one the line
+ * still counts when it has too few: it is reported broken, not posted.
+ *
+ * A rest argument whose text does not start with a quote is the raw
+ * remainder, so `/label In Progress` and `/status Won't fix` need no quoting
+ * and no escape is processed. A quoted one is a shell word like any other.
+ */
+function argumentWords(command, text, nameEnd) {
+    const words = shellWords(text.slice(nameEnd), nameEnd);
+    const last = command.args.length - 1;
+    const head = words[last];
+    if (command.args[last]?.rest &&
+        head !== undefined &&
+        !/^['"]/.test(head.raw)) {
+        words.splice(last, words.length - last, rawWord(text, head.start));
+    }
+    const required = command.args.filter((arg) => !arg.optional).length;
+    const unclosed = words.at(-1)?.unclosed === true;
+    if ((!unclosed && words.length < required) ||
+        words.length > command.args.length) {
+        return null;
+    }
+    return words;
+}
+function invalidMessage(spec, value, provider) {
+    const message = spec.kind === "enum"
+        ? `"${value}" is not one of ${spec.values.join(", ")}`
+        : `nothing named "${value}"`;
+    const suggestion = didYouMean(value, suggestionCandidates(spec, provider));
+    return suggestion === null
+        ? message
+        : `${message} (did you mean "${suggestion}"?)`;
+}
+/**
+ * Does this line, on its own, spell a command? Only whole lines count: a `/`
+ * mid-sentence is prose, and prose is the default — an unknown `/clsoe` is
+ * left exactly where it was typed rather than guessed at.
+ *
+ * A recognized line is broken, and `compile` is not called, when a quote is
+ * left open, a brace expansion goes over the limit, or a value has an
+ * `invalid` verdict. Otherwise `compile` runs and stays the authority.
+ */
+export function recognizeCommandLine(line, registry, providers) {
+    if (!line.startsWith("/"))
+        return null;
+    const text = line.trimEnd();
+    const match = COMMAND_HEAD.exec(text);
+    if (match === null)
+        return null;
+    const name = match[1];
+    const command = registry.byName.get(name);
+    if (command === undefined)
+        return null;
+    const nameEnd = name.length + 1;
+    const words = argumentWords(command, text, nameEnd);
+    if (words === null)
+        return null;
+    const args = [];
+    const verdicts = [];
+    let reason;
+    const fail = (why) => {
+        reason ??= `/${command.name}: ${why}`;
+    };
+    for (const [i, word] of words.entries()) {
+        const spec = command.args[i];
+        const provider = providerOf(spec.value, providers);
+        if (word.unclosed)
+            fail("unclosed quote");
+        let values = [word.value];
+        if (spec.multiple) {
+            const expansion = expandBraces(word, { limit: BRACE_LIMIT });
+            if (!expansion.ok) {
+                fail(`"${word.value}" ${expansion.reason}`);
+                args.push(values);
+                verdicts.push("invalid");
+                continue;
+            }
+            values = expansion.words;
+            args.push(values);
+        }
+        else {
+            args.push(word.value);
+        }
+        const each = values.map((value) => {
+            const verdict = valueVerdict(spec.value, value, provider);
+            if (verdict === "invalid") {
+                fail(invalidMessage(spec.value, value, provider));
+            }
+            return verdict;
+        });
+        const worst = worstVerdict(each) ?? "valid";
+        verdicts.push(word.unclosed ? "invalid" : worst);
+    }
+    if (reason !== undefined) {
+        return { command, words, args, verdicts, compiled: null, reason };
+    }
+    const compiled = command.compile(args);
+    if (compiled !== null)
+        return { command, words, args, verdicts, compiled };
+    const typed = text.slice(nameEnd).trim();
+    return {
+        command,
+        words,
+        args,
+        verdicts,
+        compiled,
+        reason: command.invalidReason?.(args) ??
+            (typed === ""
+                ? `/${command.name} has no target here`
+                : `/${command.name}: nothing named "${typed}"`),
+    };
+}
+/**
+ * Which lines a fenced code block covers. Line-based on purpose: 4-space code
+ * blocks cannot be told from list continuations without a full markdown parse.
+ */
+function fencedLines(lines) {
+    const inCode = lines.map(() => false);
+    let fence = null;
+    for (const [i, line] of lines.entries()) {
+        const open = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+        if (open?.[1] !== undefined) {
+            const char = open[1][0];
+            const len = open[1].length;
+            if (fence === null) {
+                fence = { char, len };
+                inCode[i] = true;
+                continue;
+            }
+            if (char === fence.char && len >= fence.len) {
+                fence = null;
+                inCode[i] = true;
+                continue;
+            }
+        }
+        if (fence !== null)
+            inCode[i] = true;
+    }
+    return inCode;
+}
+/** Line indices (0-based) that carry a recognized command. */
+export function commandLinesOf(text, registry, providers) {
+    const lines = text.split("\n");
+    const inCode = fencedLines(lines);
+    const found = new Map();
+    for (const [i, line] of lines.entries()) {
+        if (inCode[i])
+            continue;
+        const recognized = recognizeCommandLine(line, registry, providers);
+        if (recognized !== null)
+            found.set(i, recognized);
+    }
+    return found;
+}
+export function parseCommandLines(text, registry, providers) {
+    const lines = text.split("\n");
+    const found = commandLinesOf(text, registry, providers);
+    const commands = [];
+    const invalid = [];
+    const summaries = [];
+    const kept = [];
+    for (const [i, line] of lines.entries()) {
+        const recognized = found.get(i);
+        if (recognized === undefined) {
+            kept.push(line);
+            continue;
+        }
+        if (recognized.compiled === null) {
+            invalid.push({ line: line.trim(), reason: recognized.reason ?? "" });
+            continue;
+        }
+        commands.push(recognized.compiled);
+        summaries.push(recognized.command.summarize(recognized.args));
+    }
+    return { body: kept.join("\n").trim(), commands, invalid, summaries };
+}
+/** "close" / "close and label bug" — the tail of the submit button's label. */
+export function summarizeCommands(summaries) {
+    if (summaries.length <= 1)
+        return summaries.join("");
+    return `${summaries.slice(0, -1).join(", ")} and ${summaries.at(-1)}`;
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

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

package/dist/completion.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Completion at the caret, the pure half: what is being typed, where it
+ * starts and ends, and which values fit. Fetching and rendering stay with
+ * the editor that asks — a search box and a CodeMirror panel read the same
+ * slot.
+ */
+import { type CommandRegistry } from "./commands.ts";
+import { type CompiledQuerySchema, type QueryPart } from "./query.ts";
+import type { ValueOption, ValueProvider, ValueSpec } from "./values.ts";
+/** Offsets are into the query, or into the line for the command kinds. */
+export type CompletionSlot = {
+    kind: "key";
+    from: number;
+    to: number;
+    typed: string;
+    negated: boolean;
+} | {
+    kind: "value";
+    from: number;
+    to: number;
+    typed: string;
+    spec: ValueSpec;
+    key: string;
+    /** Only the current alternative of a brace group is the slot. */
+    inBraces: boolean;
+} | {
+    kind: "command";
+    from: number;
+    to: number;
+    typed: string;
+} | {
+    kind: "argument";
+    from: number;
+    to: number;
+    typed: string;
+    spec: ValueSpec;
+    command: string;
+    index: number;
+    last: boolean;
+    optional: boolean;
+    /** A rest argument's raw remainder, where a value goes in as typed. */
+    rest: boolean;
+    inBraces: boolean;
+};
+export type ValueSlot = Extract<CompletionSlot, {
+    kind: "value";
+} | {
+    kind: "argument";
+}>;
+/**
+ * What one source offers, and whether the caret is actually on something it
+ * recognises. `matched` is the whole ordering rule: a source that only
+ * *could* be useful stays below the submit row.
+ */
+export type SourceResult<Row> = {
+    matched: boolean;
+    rows: readonly Row[];
+    /** Takes only what the other sources left, and never crowds them out. */
+    yields?: boolean;
+};
+/**
+ * One offered completion. A single line: an icon, the syntax in a monospace
+ * run, and at most a very short grey note beside it — never a second line of
+ * description. The dropdown is something to glance at mid-keystroke.
+ */
+export type CompletionRow = {
+    id: string;
+    /** The syntax itself, e.g. `harness:` or `area:web`. */
+    text: string;
+    /** A few words at most, on the same line. */
+    hint?: string;
+    icon: "key" | "value";
+    /** The whole query after accepting this, and where the caret lands. */
+    apply: {
+        value: string;
+        caret: number;
+    };
+};
+/**
+ * The slot under the caret in a query: a value where the caret stands after
+ * a known key's colon, else the bare word the caret stands in (or an empty
+ * one where it stands) as a key. Null where a key cannot go at all: inside a
+ * filter's key, and inside quotes, which is how one asks for a literal.
+ */
+export declare function queryCompletionSlot(schema: CompiledQuerySchema, parts: readonly QueryPart[], query: string, caret: number): CompletionSlot | null;
+/**
+ * The slot at the end of `lineBeforeCaret`: the command word itself, or the
+ * argument the caret is in. Null where the line cannot be a command, past
+ * the last argument, and for a command that takes none.
+ */
+export declare function commandCompletionSlot<T>(registry: CommandRegistry<T>, lineBeforeCaret: string): CompletionSlot | null;
+/**
+ * The values a slot can take: the enum's set, the specials, and the
+ * provider's snapshot, in that order. `"fetch"` tells the caller to ask a
+ * `search` provider for `slot.typed` and call again with what it answered.
+ */
+export declare function slotValues(slot: ValueSlot, provider?: ValueProvider, fetched?: readonly ValueOption[]): readonly ValueOption[] | "fetch";
+/** Options that `typed` prefixes, case-insensitively. */
+export declare function filterOptions(options: readonly ValueOption[], typed: string): ValueOption[];
+/** Splice `text` over `[start, end)` and put the caret after it. */
+export declare function splice(query: string, start: number, end: number, text: string): {
+    value: string;
+    caret: number;
+};
+/**
+ * Splice, and leave the caret past a space, so that taking an offer ends a
+ * word rather than parking the caret against the next one.
+ *
+ * Only values do this. A key is completed to its colon and the value comes
+ * next with nothing in between, so a space there would have to be deleted
+ * again.
+ *
+ * The cost, taken deliberately: a value can be a comma-separated list, and
+ * closing it after one value means a second one needs a backspace. That is
+ * the rare path; ending a word is every time.
+ */
+export declare function spliceThenSpace(query: string, start: number, end: number, text: string): {
+    value: string;
+    caret: number;
+};
+/**
+ * How a value is spelled into a command argument: as one shell word, except
+ * in a rest argument's raw remainder, where quotes would be read literally.
+ */
+export declare function quoteArgument(slot: Extract<CompletionSlot, {
+    kind: "argument";
+}>, value: string): string;
+/**
+ * Keys, offered against the word the caret is in. Only a non-empty prefix of
+ * a real key counts as a match; a bare space lists them all, below submit.
+ */
+export declare function keyRows(schema: CompiledQuerySchema, query: string, slot: CompletionSlot | null): SourceResult<CompletionRow>;
+/**
+ * Values, offered whenever the caret stands where one goes. The colon is
+ * already typed by then, so the intent is not in doubt and this always counts
+ * as a match — including on an empty value, where the whole list is what the
+ * reader is asking for. `options` are offered as given; narrow them with
+ * `filterOptions` first. Inside a brace group no space follows, since the
+ * group is still open.
+ */
+export declare function valueRows(schema: CompiledQuerySchema, query: string, slot: CompletionSlot | null, options: readonly ValueOption[]): SourceResult<CompletionRow>;
+/**
+ * The offered rows, in order: **the submit row is first** unless something
+ * is genuinely being completed.
+ *
+ * The reader is typing a query, not filling in a form. Putting a completion
+ * above the submit row means Enter submits something they did not ask for,
+ * and the only evidence that they wanted one is that what they typed
+ * actually prefixes something. Everything else — the full list of keys after
+ * a space, say — is still shown, because that is how the syntax is
+ * discovered, but it waits below.
+ *
+ * `limit` is spent here rather than inside each source, so that a source
+ * added later lands in the same budget without having to remember one. The
+ * matched rows spend it first — they are what the reader is completing — the
+ * submit row is never spent, and whatever is left goes to the rest.
+ *
+ * A source marked `yields` waits for both of those to be served and takes
+ * only the remainder. History is the one that does in todou (T-270): a
+ * completion or a jump answers the string being typed right now, history
+ * answers what was searched before, and the keys are the only place the
+ * syntax can be discovered — so history is what gives way when the panel is
+ * full.
+ */
+export declare function orderRows<Row>(results: readonly SourceResult<Row>[], submit: Row, limit?: number): Row[];
+//# sourceMappingURL=completion.d.ts.map

package/dist/completion.d.ts.map

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