// suggest.js - when the composer offers suggestions and which ones. // // Pure: no GPUI, no herdr, no IO, no clock. The module answers three // questions - is the caret inside a `/` or `@` token (detect), which items fit // what was typed (rank), and how the items sit in groups when nothing was // typed (merge) - so it runs in plain Node (tests/suggest.test.mjs). // // The rules are the design's (§5): four levels of matching, ties broken by how // often the item was used and then by its name. A `/` opens the menu only at // the start of a line or after a space, so a path like /tmp/x is left alone; // an `@` opens the file menu anywhere. /** * @typedef {object} Item * @property {string} key - the name the needle is matched against * @property {string} desc - one line about the item * @property {string} [group] - Wbudowane | Projekt | Użytkownik | Terminal * @property {string} insert - the text put into the field ("/review ") * @property {number} [uses] - how often the person picked the item */ /** The built-in commands of the agent. */ export const GROUP_BUILTIN = "Wbudowane"; /** The commands of the project the pane sits in. */ export const GROUP_PROJECT = "Projekt"; /** The person's own saved snippets. */ export const GROUP_USER = "Użytkownik"; /** The commands the terminal itself understands. */ export const GROUP_TERMINAL = "Terminal"; /** The groups, in the order the menu shows them. */ export const GROUPS = [GROUP_BUILTIN, GROUP_PROJECT, GROUP_USER, GROUP_TERMINAL]; /** A name may start a word after one of these. */ const BOUNDARY = new Set([":", "-", "_", ".", "/"]); /** A command name holds no space and no path separator - "/tmp/x" is a path. */ const COMMAND_QUERY = /^[^\s/\\]*$/; /** A file name holds no space and is not empty. */ const FILE_QUERY = /^\S+$/; /** * The token at the caret: `null` when the caret is not inside one. * * A `/` counts only at the start of a line or after a space, and only when * what follows can be a command name - a slash in the middle of a word (the * second slash of /tmp/x) is a path, not a command. An `@` counts anywhere, * but it needs at least one character of a name to complete. * * @param {string} text * @param {number} caret - where the cursor is, between characters * @returns {{trigger:"/"|"@", needle:string, start:number}|null} */ export function detect(text, caret) { if (typeof text !== "string") return null; if (!Number.isInteger(caret) || caret < 0 || caret > text.length) return null; const lineStart = text.lastIndexOf("\n", Math.max(0, caret - 1)) + 1; const slash = text.lastIndexOf("/", Math.max(0, caret - 1)); if (slash >= lineStart && (slash === lineStart || /\s/.test(text[slash - 1] ?? ""))) { const needle = text.slice(slash + 1, caret); if (COMMAND_QUERY.test(needle)) return { trigger: "/", needle, start: slash }; } const at = text.lastIndexOf("@", Math.max(0, caret - 1)); if (at >= lineStart) { const needle = text.slice(at + 1, caret); if (FILE_QUERY.test(needle)) return { trigger: "@", needle, start: at }; } return null; } /** * Does this token start a line? The fuzzy levels of the ranking are for the * start of a line only - in the middle of one a name is matched by its * beginning or by a word boundary, so the composer never rewrites a path. * * @param {string} text * @param {number} index - where the trigger sits * @returns {boolean} */ export function startsLine(text, index) { if (typeof text !== "string") return true; if (!Number.isInteger(index) || index <= 0) return true; return text[index - 1] === "\n"; } /** * The items that fit the needle, best first. * * Four levels: the name begins with the needle (0), the needle sits at a * word boundary of the name (1), the needle is somewhere in the name (2), * the needle is in the description and is at least two characters long (3). * Ties go to the item used more often, then to the name. * * The fuzzy levels (2 and 3) belong to a trigger at the start of a line - * in the middle of one a name is matched by its beginning or by a word * boundary, so the composer never rewrites a path. `atLineStart` says which * of the two it is, and the caller has to say: without it the levels are off. * * @param {Item[]} items * @param {string} needle * @param {{atLineStart?:boolean}} [options] - `atLineStart: true` lets the * fuzzy levels (2 and 3) in, for a trigger at the start of a line * @returns {Item[]} */ export function rank(items, needle, options = {}) { const atLineStart = options.atLineStart === true; const query = typeof needle === "string" ? needle.toLowerCase() : ""; const list = Array.isArray(items) ? items : []; const scored = []; for (const item of list) { if (!item) continue; const level = levelOf(item, query); if (level === null) continue; if (!atLineStart && level > 1) continue; scored.push({ item, level }); } scored.sort((a, b) => { if (a.level !== b.level) return a.level - b.level; const used = (b.item.uses ?? 0) - (a.item.uses ?? 0); if (used !== 0) return used; return byName(a.item.key, b.item.key); }); return scored.map((entry) => entry.item); } /** * The items of every group in one list, the groups in the order the design * names them. Used when nothing was typed - with a needle the list is flat. * * @param {Record} groups * @returns {Item[]} */ export function merge(groups) { const source = groups && typeof groups === "object" ? groups : {}; const names = [...GROUPS, ...Object.keys(source).filter((name) => !GROUPS.includes(name))]; const merged = []; for (const name of names) { const list = source[name]; if (!Array.isArray(list)) continue; for (const item of list) { if (!item) continue; merged.push({ ...item, group: item.group ?? name }); } } return merged; } /** * How well an item matches the needle; lower is better, `null` is no match. */ function levelOf(item, query) { const name = String(item.key ?? "").toLowerCase(); const desc = String(item.desc ?? "").toLowerCase(); if (query === "") return 0; if (name.startsWith(query)) return 0; if (atBoundary(name, query)) return 1; if (name.includes(query)) return 2; if (query.length >= 2 && desc.includes(query)) return 3; return null; } /** Does the needle sit after a word boundary anywhere in the name? */ function atBoundary(name, query) { let at = name.indexOf(query); while (at > 0) { if (BOUNDARY.has(name[at - 1])) return true; at = name.indexOf(query, at + 1); } return false; } /** Names in alphabetical order, the case not counting. */ function byName(a, b) { const left = String(a ?? "").toLowerCase(); const right = String(b ?? "").toLowerCase(); if (left < right) return -1; if (left > right) return 1; return 0; }