@hesed/search 0.2.1 → 0.2.2

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @hesed/search
 $ search COMMAND
 running command...
 $ search (--version)
-@hesed/search/0.2.1 linux-x64 node-v24.16.0
+@hesed/search/0.2.2 linux-x64 node-v24.16.0
 $ search --help [COMMAND]
 USAGE
   $ search COMMAND
@@ -32,6 +32,8 @@ USAGE
 
 <!-- commands -->
 * [`search search QUERY`](#search-search-query)
+* [`search synonyms export [FILE]`](#search-synonyms-export-file)
+* [`search synonyms import FILE`](#search-synonyms-import-file)
 
 ## `search search QUERY`
 
@@ -62,5 +64,52 @@ EXAMPLES
   $ search search "update jira" --details
 ```
 
-_See code: [src/commands/search.ts](https://github.com/hesedcasa/search/blob/v0.2.1/src/commands/search.ts)_
+_See code: [src/commands/search.ts](https://github.com/hesedcasa/search/blob/v0.2.2/src/commands/search.ts)_
+
+## `search synonyms export [FILE]`
+
+Export the stored synonyms to a JSON file or stdout
+
+```
+USAGE
+  $ search synonyms export [FILE]
+
+ARGUMENTS
+  [FILE]  Output file path (prints to stdout if omitted)
+
+DESCRIPTION
+  Export the stored synonyms to a JSON file or stdout
+
+EXAMPLES
+  $ search synonyms export
+
+  $ search synonyms export ./my-synonyms.json
+```
+
+_See code: [src/commands/synonyms/export.ts](https://github.com/hesedcasa/search/blob/v0.2.2/src/commands/synonyms/export.ts)_
+
+## `search synonyms import FILE`
+
+Import synonyms from a JSON file
+
+```
+USAGE
+  $ search synonyms import FILE [--merge]
+
+ARGUMENTS
+  FILE  Path to a JSON synonyms file to import
+
+FLAGS
+  --merge  Merge with existing synonyms instead of replacing them
+
+DESCRIPTION
+  Import synonyms from a JSON file
+
+EXAMPLES
+  $ search synonyms import ./synonyms.json
+
+  $ search synonyms import ./synonyms.json --merge
+```
+
+_See code: [src/commands/synonyms/import.ts](https://github.com/hesedcasa/search/blob/v0.2.2/src/commands/synonyms/import.ts)_
 <!-- commandsstop -->

package/dist/commands/search.js

@@ -1,5 +1,6 @@
 import { Args, Command, CommandHelp, Flags, toConfiguredId } from '@oclif/core';
 import { searchCommands } from '../search-logic.js';
+import { loadStoredSynonymMap } from '../synonym-store.js';
 export default class Search extends Command {
     static args = {
         query: Args.string({ description: 'Search term to filter commands by', required: true }),
@@ -18,7 +19,8 @@ export default class Search extends Command {
     async run() {
         const { args, flags } = await this.parse(Search);
         const allCommands = this.config.commands.filter((c) => !c.hidden && c.pluginName !== '@oclif/plugin-plugins');
-        const scored = (await searchCommands(args.query, allCommands)).slice(0, flags.limit);
+        const synonyms = loadStoredSynonymMap(this.config.configDir);
+        const scored = (await searchCommands(args.query, allCommands, synonyms)).slice(0, flags.limit);
         const results = scored.map((entry) => {
             const { cmd } = entry;
             const configuredId = toConfiguredId(cmd.id, this.config);

package/dist/commands/synonyms/export.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class SynonymsExport extends Command {
+    static args: {
+        file: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/synonyms/export.js

@@ -0,0 +1,22 @@
+import { Args, Command } from '@oclif/core';
+import { writeFileSync } from 'node:fs';
+import { readSynonymGroups } from '../../synonym-store.js';
+export default class SynonymsExport extends Command {
+    static args = {
+        file: Args.string({ description: 'Output file path (prints to stdout if omitted)', required: false }),
+    };
+    static description = 'Export the stored synonyms to a JSON file or stdout';
+    static examples = ['<%= config.bin %> synonyms export', '<%= config.bin %> synonyms export ./my-synonyms.json'];
+    async run() {
+        const { args } = await this.parse(SynonymsExport);
+        const groups = readSynonymGroups(this.config.configDir);
+        const json = JSON.stringify(groups, null, 2) + '\n';
+        if (args.file) {
+            writeFileSync(args.file, json, 'utf8');
+            this.log(`Exported ${groups.length} synonym group${groups.length === 1 ? '' : 's'} → ${args.file}`);
+        }
+        else {
+            process.stdout.write(json);
+        }
+    }
+}

package/dist/commands/synonyms/import.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class SynonymsImport extends Command {
+    static args: {
+        file: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        merge: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/synonyms/import.js

@@ -0,0 +1,61 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { existsSync } from 'node:fs';
+import { synonymsPath, writeSynonymGroups } from '../../synonym-store.js';
+import { loadSynonymGroupsFromFile } from '../../synonyms.js';
+export default class SynonymsImport extends Command {
+    static args = {
+        file: Args.string({ description: 'Path to a JSON synonyms file to import', required: true }),
+    };
+    static description = 'Import synonyms from a JSON file';
+    static examples = [
+        '<%= config.bin %> synonyms import ./synonyms.json',
+        '<%= config.bin %> synonyms import ./synonyms.json --merge',
+    ];
+    static flags = {
+        merge: Flags.boolean({
+            default: false,
+            description: 'Merge with existing synonyms instead of replacing them',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SynonymsImport);
+        if (!existsSync(args.file)) {
+            this.error(`File not found: ${args.file}`);
+        }
+        const incoming = loadSynonymGroupsFromFile(args.file);
+        let groups;
+        if (flags.merge) {
+            const { readSynonymGroups } = await import('../../synonym-store.js');
+            const existing = readSynonymGroups(this.config.configDir);
+            groups = mergeSynonymGroups(existing, incoming);
+        }
+        else {
+            groups = incoming;
+        }
+        writeSynonymGroups(this.config.configDir, groups);
+        const dest = synonymsPath(this.config.configDir);
+        this.log(`Imported ${groups.length} synonym group${groups.length === 1 ? '' : 's'} → ${dest}`);
+    }
+}
+/**
+ * Merge two synonym group lists.
+ *
+ * Groups are merged when they share at least one term in common; otherwise
+ * they are appended as separate groups.
+ */
+function mergeSynonymGroups(existing, incoming) {
+    const result = existing.map((g) => [...g]);
+    for (const group of incoming) {
+        const normalizedGroup = group.map((t) => t.toLowerCase().trim()).filter(Boolean);
+        // Find any existing group that overlaps
+        const matchIndex = result.findIndex((r) => r.some((t) => normalizedGroup.includes(t.toLowerCase().trim())));
+        if (matchIndex === -1) {
+            result.push(normalizedGroup);
+        }
+        else {
+            const merged = [...new Set([...normalizedGroup, ...result[matchIndex].map((t) => t.toLowerCase().trim())])];
+            result[matchIndex] = merged;
+        }
+    }
+    return result;
+}

package/dist/search-logic.d.ts

@@ -1,3 +1,4 @@
+import { type SynonymMap } from './synonyms.js';
 export type SearchableCommand = {
     description?: string;
     id: string;
@@ -8,5 +9,5 @@ export type ScoredCommand<T extends SearchableCommand = SearchableCommand> = {
     cmd: T;
     score: number;
 };
-export declare function searchCommands<T extends SearchableCommand>(query: string, commands: T[]): Promise<Array<ScoredCommand<T>>>;
-export declare function searchCommandsLexically<T extends SearchableCommand>(query: string, commands: T[], haystack?: string[]): Array<ScoredCommand<T>>;
+export declare function searchCommands<T extends SearchableCommand>(query: string, commands: T[], synonyms?: SynonymMap): Promise<Array<ScoredCommand<T>>>;
+export declare function searchCommandsLexically<T extends SearchableCommand>(query: string, commands: T[], haystack?: string[], synonyms?: SynonymMap): Array<ScoredCommand<T>>;

package/dist/search-logic.js

@@ -1,23 +1,25 @@
 import { createRequire } from 'node:module';
+import { expandWithSynonyms } from './synonyms.js';
 const require = createRequire(import.meta.url);
 const { Index } = require('flexsearch');
-export async function searchCommands(query, commands) {
+export async function searchCommands(query, commands, synonyms = new Map()) {
     const normalizedQuery = query.trim();
     if (normalizedQuery.length === 0 || commands.length === 0)
         return [];
-    const haystack = commands.map((command) => commandSearchText(command));
-    return searchCommandsLexically(normalizedQuery, commands, haystack);
+    const haystack = commands.map((command) => expandWithSynonyms(commandSearchText(command), synonyms));
+    return searchCommandsLexically(normalizedQuery, commands, haystack, synonyms);
 }
-export function searchCommandsLexically(query, commands, haystack = commands.map((command) => commandSearchText(command))) {
+export function searchCommandsLexically(query, commands, haystack = commands.map((command) => commandSearchText(command)), synonyms = new Map()) {
     const index = createCommandSearchIndex(haystack);
-    const idxs = index.search(query, { limit: commands.length, suggest: true });
+    const expandedQuery = expandWithSynonyms(query, synonyms);
+    const idxs = index.search(expandedQuery, { limit: commands.length, suggest: true });
     if (idxs.length > 0) {
         return idxs.map((idx, rank) => ({ cmd: commands[Number(idx)], score: rank }));
     }
     // Multi-token fallback: score each command by how many individual query
     // tokens it matches. Handles queries containing unknown alias words (e.g.
     // "atlassian") that don't appear literally in any command field.
-    const tokens = query.trim().split(/\s+/).filter(Boolean);
+    const tokens = expandedQuery.trim().split(/\s+/).filter(Boolean);
     if (tokens.length <= 1)
         return [];
     const hitCount = new Map();

package/dist/synonym-store.d.ts

@@ -0,0 +1,5 @@
+import { type SynonymGroup, type SynonymMap } from './synonyms.js';
+export declare function synonymsPath(configDir: string): string;
+export declare function readSynonymGroups(configDir: string | undefined): SynonymGroup[];
+export declare function writeSynonymGroups(configDir: string, groups: SynonymGroup[]): void;
+export declare function loadStoredSynonymMap(configDir: string | undefined): SynonymMap;

package/dist/synonym-store.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildSynonymMap, parseSynonymGroups } from './synonyms.js';
+const SYNONYMS_FILENAME = 'synonyms.json';
+export function synonymsPath(configDir) {
+    return join(configDir, SYNONYMS_FILENAME);
+}
+export function readSynonymGroups(configDir) {
+    if (!configDir)
+        return [];
+    const filePath = synonymsPath(configDir);
+    if (!existsSync(filePath))
+        return [];
+    return parseSynonymGroups(readFileSync(filePath, 'utf8'));
+}
+export function writeSynonymGroups(configDir, groups) {
+    writeFileSync(synonymsPath(configDir), JSON.stringify(groups, null, 2) + '\n', 'utf8');
+}
+export function loadStoredSynonymMap(configDir) {
+    return buildSynonymMap(readSynonymGroups(configDir));
+}

package/dist/synonyms.d.ts

@@ -0,0 +1,28 @@
+export type SynonymGroup = string[];
+export type SynonymMap = Map<string, string[]>;
+/**
+ * Parse and validate a synonyms file.
+ *
+ * File format — a JSON array of synonym groups:
+ *
+ *   [
+ *     ["ticket", "issue", "bug"],
+ *     ["pr", "pull request", "merge request"],
+ *     ["repo", "repository"]
+ *   ]
+ *
+ * Every term in a group is treated as equivalent to every other term. Terms
+ * are matched case-insensitively. Multi-word terms (e.g. "pull request") are
+ * matched as whole phrases.
+ */
+export declare function parseSynonymGroups(raw: string): SynonymGroup[];
+export declare function loadSynonymGroupsFromFile(filePath: string): SynonymGroup[];
+export declare function buildSynonymMap(groups: SynonymGroup[]): SynonymMap;
+/**
+ * Return `text` with synonym expansions appended.
+ *
+ * For every term in `synonyms` that appears in `text`, all sibling terms from
+ * the same group are appended so the search index / query matches any
+ * equivalent spelling.
+ */
+export declare function expandWithSynonyms(text: string, synonyms: SynonymMap): string;

package/dist/synonyms.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+/**
+ * Parse and validate a synonyms file.
+ *
+ * File format — a JSON array of synonym groups:
+ *
+ *   [
+ *     ["ticket", "issue", "bug"],
+ *     ["pr", "pull request", "merge request"],
+ *     ["repo", "repository"]
+ *   ]
+ *
+ * Every term in a group is treated as equivalent to every other term. Terms
+ * are matched case-insensitively. Multi-word terms (e.g. "pull request") are
+ * matched as whole phrases.
+ */
+export function parseSynonymGroups(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed) ||
+        parsed.some((g) => !Array.isArray(g) || g.some((term) => typeof term !== 'string'))) {
+        throw new TypeError('Synonyms file must be a JSON array of string arrays');
+    }
+    return parsed;
+}
+export function loadSynonymGroupsFromFile(filePath) {
+    return parseSynonymGroups(readFileSync(filePath, 'utf8'));
+}
+export function buildSynonymMap(groups) {
+    const map = new Map();
+    for (const group of groups) {
+        const normalized = group.map((t) => t.toLowerCase().trim()).filter(Boolean);
+        for (const term of normalized) {
+            const others = normalized.filter((t) => t !== term);
+            const existing = map.get(term) ?? [];
+            map.set(term, [...new Set([...existing, ...others])]);
+        }
+    }
+    return map;
+}
+/**
+ * Return `text` with synonym expansions appended.
+ *
+ * For every term in `synonyms` that appears in `text`, all sibling terms from
+ * the same group are appended so the search index / query matches any
+ * equivalent spelling.
+ */
+export function expandWithSynonyms(text, synonyms) {
+    if (synonyms.size === 0)
+        return text;
+    const extras = [];
+    for (const [term, syns] of synonyms) {
+        if (containsTerm(text, term)) {
+            extras.push(...syns);
+        }
+    }
+    return extras.length > 0 ? `${text} ${extras.join(' ')}` : text;
+}
+function escapeRegex(s) {
+    // eslint-disable-next-line unicorn/prefer-string-raw
+    return s.replaceAll(/[$()*+.?[\\\]^{|}]/g, '\\$&').replaceAll(/\s+/g, String.raw `\s+`);
+}
+function containsTerm(text, term) {
+    const pattern = new RegExp(`(?<![\\w])${escapeRegex(term)}(?![\\w])`, 'i');
+    return pattern.test(text);
+}

package/oclif.manifest.json

@@ -56,7 +56,76 @@
         "commands",
         "search.js"
       ]
+    },
+    "synonyms:export": {
+      "aliases": [],
+      "args": {
+        "file": {
+          "description": "Output file path (prints to stdout if omitted)",
+          "name": "file",
+          "required": false
+        }
+      },
+      "description": "Export the stored synonyms to a JSON file or stdout",
+      "examples": [
+        "<%= config.bin %> synonyms export",
+        "<%= config.bin %> synonyms export ./my-synonyms.json"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "synonyms:export",
+      "pluginAlias": "@hesed/search",
+      "pluginName": "@hesed/search",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "synonyms",
+        "export.js"
+      ]
+    },
+    "synonyms:import": {
+      "aliases": [],
+      "args": {
+        "file": {
+          "description": "Path to a JSON synonyms file to import",
+          "name": "file",
+          "required": true
+        }
+      },
+      "description": "Import synonyms from a JSON file",
+      "examples": [
+        "<%= config.bin %> synonyms import ./synonyms.json",
+        "<%= config.bin %> synonyms import ./synonyms.json --merge"
+      ],
+      "flags": {
+        "merge": {
+          "description": "Merge with existing synonyms instead of replacing them",
+          "name": "merge",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "synonyms:import",
+      "pluginAlias": "@hesed/search",
+      "pluginName": "@hesed/search",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "synonyms",
+        "import.js"
+      ]
     }
   },
-  "version": "0.2.1"
+  "version": "0.2.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hesed/search",
   "description": "Intelligence search plugin",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "author": "Hesed",
   "bin": {
     "permission": "./bin/run.js"