opencode-agora 0.4.1 → 0.4.3

package/dist/scan.d.ts

@@ -0,0 +1,26 @@
+import type { MarketplaceItem } from './marketplace.js';
+import type { FetchLike } from './live.js';
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+export interface ScanCheck {
+    name: string;
+    label: string;
+    status: CheckStatus;
+    message: string;
+}
+export interface ScanResult {
+    id: string;
+    itemKind: 'package' | 'workflow';
+    checks: ScanCheck[];
+    summary: {
+        pass: number;
+        warn: number;
+        fail: number;
+    };
+}
+export interface ScanOptions {
+    fetcher?: FetchLike;
+    now?: () => Date;
+    githubToken?: string;
+}
+export declare function scanItem(item: MarketplaceItem, opts?: ScanOptions): Promise<ScanResult>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,kBAAkB,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;IACjC,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACvD;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAqND,wBAAsB,QAAQ,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkCjG"}

package/dist/scan.js

@@ -0,0 +1,247 @@
+import { hasPermissions, getInstallKind } from './marketplace.js';
+function tally(checks) {
+    let pass = 0, warn = 0, fail = 0;
+    for (const c of checks) {
+        if (c.status === 'pass')
+            pass++;
+        else if (c.status === 'warn')
+            warn++;
+        else
+            fail++;
+    }
+    return { pass, warn, fail };
+}
+function licenseCheck(status, message) {
+    return { name: 'license_present', label: 'License declared', status, message };
+}
+// Returns repo_reachable plus (when the repo is reachable) license_present,
+// both derived from a single GitHub repos API call. A missing license is a
+// warning, never a hard fail — many legitimate repos lack a detected license.
+async function checkRepo(item, opts) {
+    const base = {
+        name: 'repo_reachable',
+        label: 'Repository reachable'
+    };
+    if (!item.repository) {
+        return [{ ...base, status: 'pass', message: 'no repository field, skipped' }];
+    }
+    let url;
+    try {
+        url = new URL(item.repository);
+    }
+    catch {
+        return [{ ...base, status: 'pass', message: 'non-github repository, skipped' }];
+    }
+    if (url.hostname !== 'github.com') {
+        return [{ ...base, status: 'pass', message: 'non-github repository, skipped' }];
+    }
+    const path = url.pathname
+        .replace(/^\//, '')
+        .replace(/\.git$/, '')
+        .split('/')
+        .slice(0, 2)
+        .join('/');
+    const apiUrl = `https://api.github.com/repos/${path}`;
+    const headers = { Accept: 'application/vnd.github+json' };
+    if (opts.githubToken)
+        headers.Authorization = `Bearer ${opts.githubToken}`;
+    const fetcher = opts.fetcher ?? globalThis.fetch;
+    try {
+        const res = await fetcher(apiUrl, { headers, signal: AbortSignal.timeout(8000) });
+        if (res.status === 200) {
+            const reachable = { ...base, status: 'pass', message: `github.com/${path}` };
+            let license;
+            try {
+                const body = (await res.json());
+                const spdx = body.license?.spdx_id;
+                license =
+                    spdx && spdx !== 'NOASSERTION'
+                        ? licenseCheck('pass', spdx)
+                        : licenseCheck('warn', 'no license detected on the repository');
+            }
+            catch {
+                license = licenseCheck('warn', 'could not read license metadata');
+            }
+            return [reachable, license];
+        }
+        if (res.status === 404)
+            return [{ ...base, status: 'fail', message: 'repo not found' }];
+        return [{ ...base, status: 'warn', message: 'could not verify (rate limited or network)' }];
+    }
+    catch {
+        return [{ ...base, status: 'warn', message: 'could not verify (rate limited or network)' }];
+    }
+}
+async function checkNpmExists(item, opts) {
+    const base = {
+        name: 'npm_exists',
+        label: 'npm package exists'
+    };
+    if (!item.npmPackage)
+        return { ...base, status: 'pass', message: 'no npm package, skipped' };
+    const encoded = encodeURIComponent(item.npmPackage).replace('%40', '@').replace('%2F', '/');
+    const fetcher = opts.fetcher ?? globalThis.fetch;
+    try {
+        const res = await fetcher(`https://registry.npmjs.org/${encoded}/latest`, {
+            signal: AbortSignal.timeout(8000)
+        });
+        if (res.status === 200) {
+            const json = (await res.json());
+            return {
+                ...base,
+                status: 'pass',
+                message: `${item.npmPackage}@${json.version ?? 'unknown'}`
+            };
+        }
+        if (res.status === 404)
+            return { ...base, status: 'fail', message: 'package not found on npm' };
+        return { ...base, status: 'warn', message: 'could not verify (network)' };
+    }
+    catch {
+        return { ...base, status: 'warn', message: 'could not verify (network)' };
+    }
+}
+async function scanPackage(item, opts) {
+    const checks = [];
+    // 1. permissions_declared
+    const hasPerm = hasPermissions(item.permissions);
+    if (hasPerm) {
+        const parts = [];
+        if (item.permissions?.fs?.length)
+            parts.push('fs');
+        if (item.permissions?.net?.length)
+            parts.push('net');
+        if (item.permissions?.exec?.length)
+            parts.push('exec');
+        checks.push({
+            name: 'permissions_declared',
+            label: 'Permissions declared',
+            status: 'pass',
+            message: parts.join('|')
+        });
+    }
+    else {
+        checks.push({
+            name: 'permissions_declared',
+            label: 'Permissions declared',
+            status: 'warn',
+            message: 'no permissions manifest declared'
+        });
+    }
+    // 2. permission_consistency
+    const kind = getInstallKind(item);
+    if (kind === 'git-clone' && !item.permissions?.exec?.length) {
+        checks.push({
+            name: 'permission_consistency',
+            label: 'Permission consistency',
+            status: 'warn',
+            message: 'git-clone install runs shell commands; declare exec'
+        });
+    }
+    else if (kind === 'mcp-config-patch' && item.npmPackage && !item.permissions?.exec?.length) {
+        checks.push({
+            name: 'permission_consistency',
+            label: 'Permission consistency',
+            status: 'warn',
+            message: 'npx invocation runs binaries; declare exec'
+        });
+    }
+    else {
+        checks.push({
+            name: 'permission_consistency',
+            label: 'Permission consistency',
+            status: 'pass',
+            message: 'declared permissions match install kind'
+        });
+    }
+    // 3. repo_reachable (+ license_present when reachable)
+    if (item.repository) {
+        checks.push(...(await checkRepo(item, opts)));
+    }
+    // 4. npm_exists
+    if (item.npmPackage) {
+        checks.push(await checkNpmExists(item, opts));
+    }
+    // 5. recently_active
+    if (item.pushedAt) {
+        const now = opts.now ? opts.now() : new Date();
+        const days = Math.floor((now.getTime() - new Date(item.pushedAt).getTime()) / 86_400_000);
+        if (days <= 365) {
+            checks.push({
+                name: 'recently_active',
+                label: 'Recently active',
+                status: 'pass',
+                message: `pushed ${days}d ago`
+            });
+        }
+        else {
+            checks.push({
+                name: 'recently_active',
+                label: 'Recently active',
+                status: 'warn',
+                message: `last push ${days}d ago — may be unmaintained`
+            });
+        }
+    }
+    // 6. flag_count_low
+    const flags = item.flagCount ?? 0;
+    if (flags < 3) {
+        checks.push({
+            name: 'flag_count_low',
+            label: 'Flag count low',
+            status: 'pass',
+            message: `${flags} flags`
+        });
+    }
+    else if (flags < 10) {
+        checks.push({
+            name: 'flag_count_low',
+            label: 'Flag count low',
+            status: 'warn',
+            message: `${flags} flags — under review threshold`
+        });
+    }
+    else {
+        checks.push({
+            name: 'flag_count_low',
+            label: 'Flag count low',
+            status: 'fail',
+            message: `${flags} flags — would auto-hide`
+        });
+    }
+    return checks;
+}
+export async function scanItem(item, opts = {}) {
+    let checks;
+    if (item.kind === 'workflow') {
+        const n = item.flagCount ?? 0;
+        checks = [
+            {
+                name: 'workflow_kind',
+                label: 'Workflow kind',
+                status: 'pass',
+                message: 'Workflow items are inert prompts — no install side effects to scan.'
+            },
+            {
+                name: 'flag_count_low',
+                label: 'Flag count low',
+                status: n < 3 ? 'pass' : n < 10 ? 'warn' : 'fail',
+                message: n < 3
+                    ? `${n} flags`
+                    : n < 10
+                        ? `${n} flags — under review threshold`
+                        : `${n} flags — would auto-hide`
+            }
+        ];
+    }
+    else {
+        checks = await scanPackage(item, opts);
+    }
+    return {
+        id: item.id,
+        itemKind: item.kind,
+        checks,
+        summary: tally(checks)
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/scan.js.map

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

package/dist/search/catalog-index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Offline BM25 inverted-index for the Agora marketplace catalog.
+ *
+ * ## Why BM25?
+ * BM25 (Best Match 25) is a probabilistic term-frequency / inverse-document-frequency
+ * ranking function that handles two key issues with naive TF-IDF:
+ *   1. Term-frequency saturation — a token appearing 100× in a doc is not 100× as
+ *      relevant as one appearing once; BM25 saturates via (tf / (tf + k1*(1-b+b*dl/avgdl))).
+ *   2. Document-length normalization — long documents naturally accumulate more term
+ *      hits; the `b` parameter (0–1) penalizes them proportionally.
+ *
+ * ## Field weighting via token repetition
+ * Rather than maintaining separate per-field inverted lists (which complicates the
+ * index structure), we inflate the term-frequency bag at index time:
+ *   - name token contributes ×3 to TF  (most signal: users search by name)
+ *   - tags token contributes ×2         (curated semantic labels)
+ *   - id token contributes ×2           (IDs are precise matches)
+ *   - description/author/category ×1    (background context)
+ *
+ * This is equivalent to weighted field merging and requires zero extra complexity in
+ * the scoring loop.
+ *
+ * ## Fully offline, zero dependencies
+ * Matches Wave 1 "no external accounts / no network" constraint. The index is
+ * rebuilt in-memory from the item list; it never persists to disk and needs no
+ * embedding model or API key.
+ */
+export interface IndexableItem {
+    id: string;
+    name: string;
+    description: string;
+    author: string;
+    category: string;
+    tags: string[];
+}
+/** Per-document posting entry stored in the inverted list. */
+interface Posting {
+    id: string;
+    tf: number;
+}
+export interface CatalogIndex {
+    /** postings[term] = array of {id, tf} for every doc containing that term */
+    postings: Map<string, Posting[]>;
+    /** df[term] = number of distinct documents containing that term */
+    df: Map<string, number>;
+    /** docLen[id] = sum of all weighted TF values for that document */
+    docLen: Map<string, number>;
+    /** average document length across all indexed documents */
+    avgDocLen: number;
+    /** total number of indexed documents */
+    N: number;
+}
+/**
+ * Combined English stopwords + intent/filler words.
+ * Intent words are stripped so that queries like
+ * "find a tool that talks to postgres" reduce to their content terms.
+ */
+export declare const STOPWORDS: Set<string>;
+/**
+ * Tokenize text for indexing or querying:
+ *   - lowercase
+ *   - split on non-alphanumeric runs
+ *   - drop tokens shorter than 2 characters
+ *   - drop STOPWORDS
+ *
+ * Deterministic: identical input always yields identical output.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Developer-term synonym map. Applied ONLY during query tokenization, not at
+ * index time, so documents are indexed verbatim (no spurious term inflation).
+ *
+ * When a query token matches a key, its synonyms are added as additional query
+ * terms (deduped). This allows short aliases ("db", "k8s") to match their full
+ * forms in document text.
+ */
+export declare const SYNONYMS: Record<string, string[]>;
+/**
+ * Tokenize a query string and expand synonyms.
+ * Returns a deduplicated array of tokens (original + synonym expansions).
+ */
+export declare function tokenizeQuery(text: string): string[];
+/**
+ * Build a BM25 inverted index from a list of indexable items.
+ *
+ * Field weighting is achieved by repeating tokens in the TF bag:
+ *   name ×3, tags ×2, id ×2, description ×1, author ×1, category ×1
+ */
+export declare function buildIndex(items: IndexableItem[]): CatalogIndex;
+/**
+ * Search the index with BM25 scoring.
+ *
+ * @param index   - built by buildIndex()
+ * @param query   - raw query string (will be tokenized + synonym-expanded)
+ * @param opts    - BM25 hyperparameters (defaults: k1=1.5, b=0.75)
+ * @returns       - scored results sorted by score descending; empty array if
+ *                  query is blank or no documents match
+ */
+export declare function searchIndex(index: CatalogIndex, query: string, opts?: {
+    k1?: number;
+    b?: number;
+}): {
+    id: string;
+    score: number;
+}[];
+export {};
+//# sourceMappingURL=catalog-index.d.ts.map

package/dist/search/catalog-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-index.d.ts","sourceRoot":"","sources":["../../src/search/catalog-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,8DAA8D;AAC9D,UAAU,OAAO;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,mEAAmE;IACnE,EAAE,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,mEAAmE;IACnE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;CACX;AAID;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,GAAG,CAAC,MAAM,CAiFhC,CAAC;AAIH;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/C;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAsB7C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAYpD;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,YAAY,CAqD/D;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAoCjC"}

package/dist/search/catalog-index.js

@@ -0,0 +1,276 @@
+/**
+ * Offline BM25 inverted-index for the Agora marketplace catalog.
+ *
+ * ## Why BM25?
+ * BM25 (Best Match 25) is a probabilistic term-frequency / inverse-document-frequency
+ * ranking function that handles two key issues with naive TF-IDF:
+ *   1. Term-frequency saturation — a token appearing 100× in a doc is not 100× as
+ *      relevant as one appearing once; BM25 saturates via (tf / (tf + k1*(1-b+b*dl/avgdl))).
+ *   2. Document-length normalization — long documents naturally accumulate more term
+ *      hits; the `b` parameter (0–1) penalizes them proportionally.
+ *
+ * ## Field weighting via token repetition
+ * Rather than maintaining separate per-field inverted lists (which complicates the
+ * index structure), we inflate the term-frequency bag at index time:
+ *   - name token contributes ×3 to TF  (most signal: users search by name)
+ *   - tags token contributes ×2         (curated semantic labels)
+ *   - id token contributes ×2           (IDs are precise matches)
+ *   - description/author/category ×1    (background context)
+ *
+ * This is equivalent to weighted field merging and requires zero extra complexity in
+ * the scoring loop.
+ *
+ * ## Fully offline, zero dependencies
+ * Matches Wave 1 "no external accounts / no network" constraint. The index is
+ * rebuilt in-memory from the item list; it never persists to disk and needs no
+ * embedding model or API key.
+ */
+// ── Stopwords ─────────────────────────────────────────────────────────────────
+/**
+ * Combined English stopwords + intent/filler words.
+ * Intent words are stripped so that queries like
+ * "find a tool that talks to postgres" reduce to their content terms.
+ */
+export const STOPWORDS = new Set([
+    // English function words
+    'the',
+    'a',
+    'an',
+    'to',
+    'of',
+    'for',
+    'and',
+    'or',
+    'with',
+    'that',
+    'this',
+    'my',
+    'i',
+    'in',
+    'on',
+    'is',
+    'are',
+    'it',
+    'by',
+    'at',
+    'as',
+    'be',
+    'was',
+    'has',
+    'have',
+    'not',
+    'its',
+    'from',
+    'into',
+    'than',
+    'but',
+    'about',
+    // Intent / filler words common in natural-language queries
+    'find',
+    'search',
+    'show',
+    'get',
+    'need',
+    'want',
+    'looking',
+    'something',
+    'anything',
+    'tool',
+    'tools',
+    'thing',
+    'things',
+    'does',
+    'do',
+    'help',
+    'please',
+    'can',
+    'give',
+    'use',
+    'using',
+    'used',
+    'like',
+    'also',
+    'which',
+    'how',
+    'what',
+    'where',
+    'when',
+    'why',
+    'who',
+    'some',
+    'any',
+    'all',
+    'talks',
+    'talk',
+    'connect',
+    'connects',
+    'access',
+    'accesses',
+    'let',
+    'lets',
+    'work',
+    'works',
+    'support',
+    'supports'
+]);
+// ── Tokenizer ─────────────────────────────────────────────────────────────────
+/**
+ * Tokenize text for indexing or querying:
+ *   - lowercase
+ *   - split on non-alphanumeric runs
+ *   - drop tokens shorter than 2 characters
+ *   - drop STOPWORDS
+ *
+ * Deterministic: identical input always yields identical output.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+// ── Synonyms (query-side expansion only) ─────────────────────────────────────
+/**
+ * Developer-term synonym map. Applied ONLY during query tokenization, not at
+ * index time, so documents are indexed verbatim (no spurious term inflation).
+ *
+ * When a query token matches a key, its synonyms are added as additional query
+ * terms (deduped). This allows short aliases ("db", "k8s") to match their full
+ * forms in document text.
+ */
+export const SYNONYMS = {
+    db: ['database'],
+    k8s: ['kubernetes'],
+    k8: ['kubernetes'],
+    postgres: ['postgresql', 'database'],
+    pg: ['postgresql', 'database'],
+    js: ['javascript'],
+    ts: ['typescript'],
+    ai: ['llm'],
+    auth: ['authentication'],
+    vcs: ['git'],
+    ml: ['machine', 'learning'],
+    api: ['integration'],
+    cli: ['command'],
+    ui: ['interface'],
+    gh: ['github'],
+    gl: ['gitlab'],
+    aws: ['amazon'],
+    gcp: ['google'],
+    kv: ['cache'],
+    nosql: ['database'],
+    sql: ['database']
+};
+/**
+ * Tokenize a query string and expand synonyms.
+ * Returns a deduplicated array of tokens (original + synonym expansions).
+ */
+export function tokenizeQuery(text) {
+    const base = tokenize(text);
+    const expanded = new Set(base);
+    for (const token of base) {
+        const syns = SYNONYMS[token];
+        if (syns) {
+            for (const syn of syns) {
+                expanded.add(syn);
+            }
+        }
+    }
+    return Array.from(expanded);
+}
+// ── Index builder ─────────────────────────────────────────────────────────────
+/**
+ * Build a BM25 inverted index from a list of indexable items.
+ *
+ * Field weighting is achieved by repeating tokens in the TF bag:
+ *   name ×3, tags ×2, id ×2, description ×1, author ×1, category ×1
+ */
+export function buildIndex(items) {
+    const postings = new Map();
+    const df = new Map();
+    const docLen = new Map();
+    let totalLen = 0;
+    for (const item of items) {
+        // Build weighted TF bag for this document
+        const tfBag = new Map();
+        function addTokens(text, weight) {
+            for (const token of tokenize(text)) {
+                tfBag.set(token, (tfBag.get(token) ?? 0) + weight);
+            }
+        }
+        addTokens(item.name, 3);
+        for (const tag of item.tags) {
+            addTokens(tag, 2);
+        }
+        addTokens(item.id, 2);
+        addTokens(item.description, 1);
+        addTokens(item.author, 1);
+        addTokens(item.category, 1);
+        // Document length = sum of weighted TFs
+        let dl = 0;
+        for (const tf of tfBag.values()) {
+            dl += tf;
+        }
+        docLen.set(item.id, dl);
+        totalLen += dl;
+        // Update postings and DF
+        for (const [term, tf] of tfBag.entries()) {
+            // DF: count this document once per term
+            df.set(term, (df.get(term) ?? 0) + 1);
+            // Postings list
+            let list = postings.get(term);
+            if (!list) {
+                list = [];
+                postings.set(term, list);
+            }
+            list.push({ id: item.id, tf });
+        }
+    }
+    const N = items.length;
+    const avgDocLen = N > 0 ? totalLen / N : 1;
+    return { postings, df, docLen, avgDocLen, N };
+}
+// ── BM25 scorer ───────────────────────────────────────────────────────────────
+/**
+ * Search the index with BM25 scoring.
+ *
+ * @param index   - built by buildIndex()
+ * @param query   - raw query string (will be tokenized + synonym-expanded)
+ * @param opts    - BM25 hyperparameters (defaults: k1=1.5, b=0.75)
+ * @returns       - scored results sorted by score descending; empty array if
+ *                  query is blank or no documents match
+ */
+export function searchIndex(index, query, opts) {
+    if (!query || !query.trim())
+        return [];
+    const k1 = opts?.k1 ?? 1.5;
+    const b = opts?.b ?? 0.75;
+    const { postings, df, docLen, avgDocLen, N } = index;
+    const queryTokens = tokenizeQuery(query);
+    if (queryTokens.length === 0)
+        return [];
+    // Accumulate scores per document
+    const scores = new Map();
+    for (const term of queryTokens) {
+        const list = postings.get(term);
+        if (!list)
+            continue;
+        const termDf = df.get(term) ?? 0;
+        // IDF with smoothing (Robertson-Sparck Jones):
+        //   idf = log((N - df + 0.5) / (df + 0.5) + 1)
+        const idf = Math.log((N - termDf + 0.5) / (termDf + 0.5) + 1);
+        for (const { id, tf } of list) {
+            const dl = docLen.get(id) ?? avgDocLen;
+            const norm = tf / (tf + k1 * (1 - b + b * (dl / avgDocLen)));
+            const contribution = idf * norm;
+            scores.set(id, (scores.get(id) ?? 0) + contribution);
+        }
+    }
+    if (scores.size === 0)
+        return [];
+    return Array.from(scores.entries())
+        .filter(([, score]) => score > 0)
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}
+//# sourceMappingURL=catalog-index.js.map