@orz/query 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright 2026 the orzui team
+Copyright 2026 the todou team
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @orz/query
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The grammar half of a search box and a slash-command composer, driven by a schema the app supplies:
+value specs, a query parser with diagnostics, a command registry and line parser, shell-style words,
+brace expansion and completion locators.
+
+It has no runtime dependencies and does not use React or the DOM, so an app's server, CLI and web
+client can import the same module and read a query or a command line the same way. The React and
+CodeMirror halves live in `@orz/ui` (`QueryBox`, `HighlightedInput`) and `@orz/ui-codemirror`.
+
+## Install
+
+```bash
+pnpm add @orz/query
+```
+
+## Value specs
+
+A qualifier value and a command argument are both a `ValueSpec`: an `enum` the schema knows, a
+`named` value the app resolves through a provider (labels, members), or a `free` value. Providers
+are passed at the point of use, so the schema itself stays static and shareable with a server:
+
+```ts
+import { valueVerdict } from "@orz/query";
+
+const providers = {
+  label: { options: [{ value: "kind:bug" }, { value: "area:web" }] },
+  member: { search: (prefix, signal) => fetchMembers(prefix, signal) },
+};
+
+valueVerdict({ kind: "named", source: "label" }, "kind:bug", providers.label); // "valid"
+```
+
+## Queries
+
+```ts
+import { defineQuerySchema, parseQuery, queryFilters } from "@orz/query";
+
+const schema = defineQuerySchema({
+  qualifiers: {
+    state: { value: { kind: "enum", values: ["open", "closed"] }, hint: "open or closed" },
+    label: { value: { kind: "named", source: "label" } },
+    assignee: { value: { kind: "named", source: "member", special: ["@me"] } },
+  },
+  braces: true,
+});
+
+const parts = parseQuery(schema, 'label:area:{web,ui} -state:closed "deploy failed"');
+queryFilters(parts);
+// [{ key: "label", negated: false, values: ["area:web", "area:ui"] },
+//  { key: "state", negated: true, values: ["closed"] }]
+```
+
+Unknown keys are plain text, so `https://app.example` and `12:30` stay searchable. The parts tile
+the input, which is what lets a highlighter paint under an `<input>`. `escapes: "shell"` switches
+quoting to shell rules (`label:'a,b'`, `don\'t`); the default keeps backslashes ordinary.
+
+## Slash commands
+
+```ts
+import { createCommandRegistry, parseCommandLines } from "@orz/query";
+
+const registry = createCommandRegistry([
+  {
+    name: "close",
+    detail: "→ Closed",
+    args: [],
+    summarize: () => "close",
+    compile: () => ({ type: "close" }),
+  },
+  {
+    name: "label",
+    detail: "add labels",
+    args: [{ name: "label", value: { kind: "named", source: "label" }, rest: true, multiple: true }],
+    summarize: ([labels]) => `label ${[labels].flat().join(", ")}`,
+    compile: ([labels]) => ({ type: "label", names: [labels].flat() }),
+  },
+]);
+
+parseCommandLines("Looks done.\n/label {kind:bug,area:web}\n/close", registry, providers);
+// body: "Looks done.", commands: [{ type: "label", … }, { type: "close" }]
+```
+
+A command is a whole line starting with `/name`; anything else, including `/close the door`, is
+prose. Arguments are shell words, a `rest` argument takes the remainder of the line unquoted, and
+brace expansion applies only to arguments declared `multiple`, which `compile` receives as a list.
+A value with an `invalid` verdict, an unclosed quote or an expansion past 64 values breaks the line
+before `compile` runs; the reason lands in `invalid`.
+
+## Completion
+
+`queryCompletionSlot` and `commandCompletionSlot` say what is being typed at the caret: a key, a
+value, a command or an argument, with its extent and value spec. Inside a brace group the slot is
+only the current alternative. `slotValues` lists what fits (or answers `"fetch"` for a `search`
+provider), `keyRows` and `valueRows` turn a query slot into rows that carry the rewritten query,
+and `orderRows` keeps the submit row first unless something is genuinely being completed.
+
+## Building blocks
+
+- `shellWords(text)` splits shell-style words, recording which characters were quoted;
+  `quoteShellWord(value)` quotes a value so it reads back as one word.
+- `expandBraces(word)` expands bash's comma form (`{a,b}`, nested, at most 64 words);
+  quoted and escaped braces stay literal.
+- `didYouMean(value, candidates)` suggests the closest candidate within a small edit distance.

package/dist/braces.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Brace expansion, bash's comma form: `{a,b}` → `a`, `b`; adjacent text
+ * distributes; groups multiply left to right and nest. Text that merely
+ * contains braces is not changed: a group needs an unquoted comma at its own
+ * level, so `{}`, `{a}` and an unclosed `{` stay literal. Sequence
+ * expressions (`{1..5}`) are not supported and stay literal too.
+ */
+import { type ShellWord } from "./shell-words.ts";
+export type BraceExpansion = {
+    ok: true;
+    words: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Fail rather than cut, the way a query with too many terms is rejected. */
+export declare const BRACE_LIMIT = 64;
+/** One character; only an active one can group or separate. */
+export type BraceChar = {
+    ch: string;
+    active: boolean;
+};
+/** A plain string is treated as entirely unquoted. */
+export declare function expandBraces(word: ShellWord | string, options?: {
+    limit?: number;
+}): BraceExpansion;
+/**
+ * For readings that are not shell words, such as plain mode's quoted
+ * alternatives, whose quotes carry no escapes.
+ */
+export declare function expandBraceChars(chars: BraceChar[], limit: number): BraceExpansion;
+//# sourceMappingURL=braces.d.ts.map

package/dist/braces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"braces.d.ts","sourceRoot":"","sources":["../src/braces.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAgB,MAAM,kBAAkB,CAAC;AAEhE,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAC7B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC,6EAA6E;AAC7E,eAAO,MAAM,WAAW,KAAK,CAAC;AAE9B,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAqHxD,sDAAsD;AACtD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,GAAG,MAAM,EACxB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3B,cAAc,CAEhB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,MAAM,GACZ,cAAc,CAShB"}

package/dist/braces.js

@@ -0,0 +1,127 @@
+/**
+ * Brace expansion, bash's comma form: `{a,b}` → `a`, `b`; adjacent text
+ * distributes; groups multiply left to right and nest. Text that merely
+ * contains braces is not changed: a group needs an unquoted comma at its own
+ * level, so `{}`, `{a}` and an unclosed `{` stay literal. Sequence
+ * expressions (`{1..5}`) are not supported and stay literal too.
+ */
+import { segmentValue } from "./shell-words.js";
+/** Fail rather than cut, the way a query with too many terms is rejected. */
+export const BRACE_LIMIT = 64;
+/** Quoted and escaped characters are literal; only bare ones can group. */
+function charsOf(word) {
+    if (typeof word === "string") {
+        return Array.from(word, (ch) => ({ ch, active: true }));
+    }
+    const chars = [];
+    for (const segment of word.segments) {
+        const active = segment.quoted === "none";
+        for (const ch of segmentValue(word, segment))
+            chars.push({ ch, active });
+    }
+    return chars;
+}
+const isActive = (chars, i, ch) => chars[i]?.active === true && chars[i]?.ch === ch;
+/**
+ * Pairs each bare `{` with its `}`, then keeps the pairs that have a bare
+ * comma at their own level. Returns open index → close index, plus the
+ * own-level commas of each group.
+ */
+function findGroups(chars) {
+    const pairs = [];
+    const stack = [];
+    for (let i = 0; i < chars.length; i += 1) {
+        if (isActive(chars, i, "{"))
+            stack.push(i);
+        else if (isActive(chars, i, "}") && stack.length > 0) {
+            pairs.push({ open: stack.pop(), close: i });
+        }
+    }
+    const closeOf = new Map(pairs.map((p) => [p.open, p.close]));
+    const groups = new Map();
+    for (const { open, close } of pairs) {
+        const commas = [];
+        for (let i = open + 1; i < close; i += 1) {
+            const nested = closeOf.get(i);
+            if (nested !== undefined) {
+                i = nested;
+                continue;
+            }
+            if (isActive(chars, i, ","))
+                commas.push(i);
+        }
+        if (commas.length > 0)
+            groups.set(open, { close, commas });
+    }
+    return groups;
+}
+class OverLimit extends Error {
+}
+/**
+ * Every kept group has at least two alternatives, so nesting deeper than the
+ * limit already expands past it; failing here keeps the recursion shallow.
+ * The 256 cap protects the stack from a large custom limit.
+ */
+function parse(chars, groups, from, to, depth, limit) {
+    if (depth > Math.min(limit, 256))
+        throw new OverLimit();
+    const items = [];
+    let text = "";
+    for (let i = from; i < to; i += 1) {
+        const group = groups.get(i);
+        if (group === undefined) {
+            text += chars[i].ch;
+            continue;
+        }
+        if (text !== "")
+            items.push(text);
+        text = "";
+        const bounds = [i, ...group.commas, group.close];
+        const alternatives = [];
+        for (let b = 0; b + 1 < bounds.length; b += 1) {
+            alternatives.push(parse(chars, groups, bounds[b] + 1, bounds[b + 1], depth + 1, limit));
+        }
+        items.push({ alternatives });
+        i = group.close;
+    }
+    if (text !== "")
+        items.push(text);
+    return items;
+}
+function expand(items, limit) {
+    let words = [""];
+    for (const item of items) {
+        if (typeof item === "string") {
+            words = words.map((w) => w + item);
+            continue;
+        }
+        const tails = item.alternatives.flatMap((alt) => expand(alt, limit));
+        if (tails.length > limit || words.length * tails.length > limit) {
+            throw new OverLimit();
+        }
+        // Prefix-major, which is bash's order: `{a,b}{c,d}` → ac ad bc bd.
+        words = words.flatMap((w) => tails.map((t) => w + t));
+    }
+    return words;
+}
+/** A plain string is treated as entirely unquoted. */
+export function expandBraces(word, options) {
+    return expandBraceChars(charsOf(word), options?.limit ?? BRACE_LIMIT);
+}
+/**
+ * For readings that are not shell words, such as plain mode's quoted
+ * alternatives, whose quotes carry no escapes.
+ */
+export function expandBraceChars(chars, limit) {
+    const groups = findGroups(chars);
+    try {
+        const items = parse(chars, groups, 0, chars.length, 0, limit);
+        return { ok: true, words: expand(items, limit) };
+    }
+    catch (error) {
+        if (!(error instanceof OverLimit))
+            throw error;
+        return { ok: false, reason: `expands to more than ${limit} values` };
+    }
+}
+//# sourceMappingURL=braces.js.map

package/dist/braces.js.map

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

package/dist/commands.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { type ShellWord } from "./shell-words.ts";
+import { type ValueProviders, type ValueSpec, type ValueVerdict } from "./values.ts";
+export type ArgSpec = {
+    /** Shown in the panel: `<label>`. */
+    name: string;
+    value: ValueSpec;
+    /** Only trailing arguments may be optional. */
+    optional?: boolean;
+    /** The last argument may take the rest of the line. */
+    rest?: boolean;
+    /** Brace expansion applies, and the argument is a list. */
+    multiple?: boolean;
+};
+/** `string` for a plain argument, `readonly string[]` for a `multiple` one. */
+export type ArgValue = string | readonly string[];
+/**
+ * `args` handed to `summarize`, `compile` and `invalidReason` are positional:
+ * an optional argument that was not typed is absent, so the array is shorter.
+ */
+export type CommandDef<T> = {
+    /** The word after the slash; must match `/^[a-z0-9-]+$/`. */
+    name: string;
+    /** One-line panel description, e.g. "→ Done". */
+    detail: string;
+    args: readonly ArgSpec[];
+    /** Summary for the submit button, e.g. "close" or "label area:web". */
+    summarize: (args: readonly ArgValue[]) => string;
+    /** Null when the arguments name nothing that exists. */
+    compile: (args: readonly ArgValue[]) => T | null;
+    /** Why these arguments compiled to nothing; a generic message otherwise. */
+    invalidReason?: (args: readonly ArgValue[]) => string;
+};
+export type CommandRegistry<T> = {
+    commands: readonly CommandDef<T>[];
+    byName: ReadonlyMap<string, CommandDef<T>>;
+};
+/**
+ * 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 declare function createCommandRegistry<T>(commands: readonly CommandDef<T>[]): CommandRegistry<T>;
+/**
+ * `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 declare function slugifyCommandName(name: string): string;
+export type RecognizedLine<T> = {
+    command: CommandDef<T>;
+    /**
+     * One word per argument typed, in the order of `args`, with offsets in the
+     * line. An unquoted rest argument is one word over the raw remainder.
+     */
+    words: ShellWord[];
+    args: ArgValue[];
+    /**
+     * Each argument's verdict; a `multiple` one has the worst among its
+     * values, and an unclosed quote or a failed expansion is `invalid`.
+     */
+    verdicts: ValueVerdict[];
+    /** Null: recognized, but broken. */
+    compiled: T | null;
+    /** Why it is broken. */
+    reason?: string;
+};
+/** A rest argument's remainder, read with no quoting at all. */
+export declare function rawWord(text: string, start: number): ShellWord;
+/**
+ * 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 declare function recognizeCommandLine<T>(line: string, registry: CommandRegistry<T>, providers?: ValueProviders): RecognizedLine<T> | null;
+export type ParsedDraft<T> = {
+    /** The draft with every recognized command line removed. */
+    body: string;
+    commands: T[];
+    /** Recognized but broken — an argument that names nothing, say. */
+    invalid: {
+        line: string;
+        reason: string;
+    }[];
+    /** Submit-button material: one summary per recognized command, in order. */
+    summaries: string[];
+};
+/** Line indices (0-based) that carry a recognized command. */
+export declare function commandLinesOf<T>(text: string, registry: CommandRegistry<T>, providers?: ValueProviders): Map<number, RecognizedLine<T>>;
+export declare function parseCommandLines<T>(text: string, registry: CommandRegistry<T>, providers?: ValueProviders): ParsedDraft<T>;
+/** "close" / "close and label bug" — the tail of the submit button's label. */
+export declare function summarizeCommands(summaries: readonly string[]): string;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

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