@devilsdev/rag-pipeline-utils 1.0.1 → 2.0.0

package/.codecov.yml

@@ -0,0 +1,21 @@
+# .codecov.yml
+
+codecov:
+  notify:
+    after_n_builds: 1
+
+coverage:
+  status:
+    project:
+      default:
+        target: 90%
+        threshold: 5%
+    patch:
+      default:
+        target: 90%
+        threshold: 5%
+
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  require_changes: false

package/.github/workflows/ci.yml

@@ -44,3 +44,21 @@ jobs:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 👈 critical for npm publi
         run: npx semantic-release
+
+      - name: 🧪 Run Tests with Coverage
+        run: npm test
+
+      - name: Validate Fixtures
+        run: npm run validate-fixtures
+      
+      - name: Lint code
+        run: npm run lint
+      
+      
+      - name: 📊 Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: DevilsDev/rag-pipeline-utils
+
+      

package/.husky/pre-commit

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run validate-fixtures && npm run lint
+npx lint-staged

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+# [2.0.0](https://github.com/DevilsDev/rag-pipeline-utils/compare/v1.0.1...v2.0.0) (2025-04-17)
+
+
+### Bug Fixes
+
+* **ci:** correct .ragrc.json plugin paths and CLI test cwd to resolve plugin loading in CI ([911c23b](https://github.com/DevilsDev/rag-pipeline-utils/commit/911c23b1d3ddb9e2d938b37f4422a5d81995e97f))
+* **ci:** resolve plugin path error in .ragrc.json for GitHub Actions compatibility ([affc739](https://github.com/DevilsDev/rag-pipeline-utils/commit/affc739d5c4ff2070b1a1ca0ccf3f9137d6cee5a))
+* **ci:** resolve plugin path failures in .ragrc.json during CLI integration tests ([04b977b](https://github.com/DevilsDev/rag-pipeline-utils/commit/04b977b3b745fa3d3ab47c84b2aeee3285896068))
+* **cli:** correct path to load-plugin-config.js after moving to /src/config ([f743498](https://github.com/DevilsDev/rag-pipeline-utils/commit/f743498ec32e03151eda9ba7fe5886bda8da792f))
+* **config:** use default export when importing plugin registry ([ef8dce1](https://github.com/DevilsDev/rag-pipeline-utils/commit/ef8dce12bfab62bc9faec764198b98c0c356472e))
+* **test:** ensure .ragrc.json copied to project root for CLI fallback in CI ([31bd2b8](https://github.com/DevilsDev/rag-pipeline-utils/commit/31bd2b844279fb0404056d9929e5f28f9127eb12))
+* **tests:** define __dirname manually for ESM compatibility in CLI integration test ([18b8dad](https://github.com/DevilsDev/rag-pipeline-utils/commit/18b8dadabb852243dda2b78de048c71106a759fc))
+
+
+### Features
+
+* **ci:** integrate full fixture validation, schema contracts, and CLI test flow ([2b57fe9](https://github.com/DevilsDev/rag-pipeline-utils/commit/2b57fe90e64a806815c1f66f5e2a745780270ce6))
+* **cli:** dynamic plugin registration with config fallback and middleware injection ([cc24b7e](https://github.com/DevilsDev/rag-pipeline-utils/commit/cc24b7e74d0a2630eb1c6d2def69b370329dcc2b))
+* **plugins:** enable dynamic plugin registration from JSON config ([d81d6d7](https://github.com/DevilsDev/rag-pipeline-utils/commit/d81d6d7d5f2d21b5a46b379b530c162ba9c30398))
+* **testing:** integrate full fixture and validation setup for CLI + reranker ([ab96037](https://github.com/DevilsDev/rag-pipeline-utils/commit/ab9603765594e7718e2688b80797e1f5e8afe86f))
+
+
+### BREAKING CHANGES
+
+* **cli:**  now requires named options for middleware injection; existing usage must be updated.
+
+## [1.0.2] - 2025-04-15
+### Fixed
+- Corrected plugin path resolution in `.ragrc.json` fixture for CI compatibility.
+- Resolved `ERR_MODULE_NOT_FOUND` during CLI integration tests in GitHub Actions.
+- Ensured consistent module resolution across environments (Windows, Linux, CI).
+
+
 ## [1.0.1](https://github.com/DevilsDev/rag-pipeline-utils/compare/v1.0.0...v1.0.1) (2025-04-14)
 
 

package/__tests__/fixtures/.ragrc.json

@@ -0,0 +1,8 @@
+{
+  "loader": { "pdf": "./src/mocks/pdf-loader.js" },
+  "embedder": { "openai": "./src/mocks/openai-embedder.js" },
+  "retriever": { "pinecone": "./src/mocks/pinecone-retriever.js" },
+  "llm": { "openai": "./src/mocks/openai-llm.js" },
+  "namespace": "cli-config-test",
+  "pipeline": ["loader", "embedder", "retriever"]
+}

package/__tests__/fixtures/invalid-ragrc.json

@@ -0,0 +1,4 @@
+{
+  "loader": "./src/mocks/pdf-loader.js",
+  "namespace": 12345
+}

package/__tests__/fixtures/src/mocks/openai-embedder.js

@@ -0,0 +1,16 @@
+/**
+ * Mock OpenAI Embedder Plugin
+ * Implements: embedder.embed(docs), embedder.embedQuery(query)
+ */
+export default class OpenAIEmbedder {
+  embed(documents) {
+    return documents.map(doc => ({
+      id: doc.id,
+      values: [0.1, 0.2, 0.3],
+    }));
+  }
+
+  embedQuery(query) {
+    return [0.1, 0.2, 0.3];
+  }
+}

package/__tests__/fixtures/src/mocks/openai-llm.js

@@ -0,0 +1,9 @@
+/**
+ * Mock OpenAI LLM Plugin
+ * Implements: llm.ask(prompt)
+ */
+export default class OpenAILLM {
+  ask(prompt) {
+    return `Answer: Mocked response to "${prompt}"`;
+  }
+}

package/__tests__/fixtures/src/mocks/pdf-loader.js

@@ -0,0 +1,17 @@
+/**
+ * Mock PDF Loader Plugin
+ * Implements: loader.load(filePath)
+ */
+export default class PdfLoader {
+  /**
+   * Loads a file and returns mock document chunks.
+   * @param {string} filePath
+   * @returns {Array<{ id: string, content: string }>}
+   */
+  load(filePath) {
+    return [
+      { id: 'doc1', content: `Loaded content from ${filePath}` },
+      { id: 'doc2', content: 'Second document content' },
+    ];
+  }
+}

package/__tests__/fixtures/src/mocks/pinecone-retriever.js

@@ -0,0 +1,26 @@
+/**
+ * Mock Pinecone Retriever Plugin
+ * Implements: retriever.store(vectors), retriever.search(queryVector)
+ */
+export default class PineconeRetriever {
+  constructor() {
+    this._store = [];
+  }
+
+  /**
+   * Stores embedded vectors.
+   * @param {Array<{ id: string, values: number[] }>} vectors
+   */
+  store(vectors) {
+    this._store = vectors;
+  }
+
+  /**
+   * Searches mock memory and returns matching docs.
+   * @param {number[]} queryVector
+   * @returns {Array<{ id: string, score: number }>}
+   */
+  search(queryVector) {
+    return this._store.map(v => ({ id: v.id, score: 0.99 }));
+  }
+}

package/__tests__/fixtures/valid-ragrc.json

@@ -0,0 +1,16 @@
+{
+  "loader": {
+    "pdf": "./src/mocks/pdf-loader.js"
+  },
+  "embedder": {
+    "openai": "./src/mocks/openai-embedder.js"
+  },
+  "retriever": {
+    "pinecone": "./src/mocks/pinecone-retriever.js"
+  },
+  "llm": {
+    "openai": "./src/mocks/openai-llm.js"
+  },
+  "namespace": "cli-config-test",
+  "pipeline": ["loader", "embedder", "retriever"]
+}

package/__tests__/integration/cli/config-flow.test.js

@@ -1,29 +1,98 @@
 /**
- * Version: 0.1.3
- * Description: Integration test for CLI with config fallback
+ * Version: 1.1.0
+ * Description: Final CLI config fallback integration test with fixture mock copying and validation
  * Author: Ali Kahwaji
  */
 
 import { execSync } from 'child_process';
-import path from 'path';
+import {
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  copyFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync
+} from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
-const CLI_PATH = path.resolve('bin/cli.js');
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = resolve(__filename, '..');
+
+const CLI_PATH = resolve('bin/cli.js');
+const TEMP_TEST_DIR = resolve('__tests__/__temp__/cli-config-fallback');
+const FIXTURE_CONFIG = join(TEMP_TEST_DIR, '.ragrc.json');
+const FIXTURE_PDF = resolve('__tests__/fixtures/sample.pdf');
+
+// Fixture sources
+const FIXTURE_SRC = resolve('__tests__/fixtures/src/mocks');
+const PDF_LOADER_SRC = join(FIXTURE_SRC, 'pdf-loader.js');
+const EMBEDDER_SRC = join(FIXTURE_SRC, 'openai-embedder.js');
+const RETRIEVER_SRC = join(FIXTURE_SRC, 'pinecone-retriever.js');
+const LLM_SRC = join(FIXTURE_SRC, 'openai-llm.js');
+
+const FIXTURE_CONFIG_OBJECT = {
+  loader: { pdf: './src/mocks/pdf-loader.js' },
+  embedder: { openai: './src/mocks/openai-embedder.js' },
+  retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
+  llm: { openai: './src/mocks/openai-llm.js' },
+  namespace: 'cli-config-test',
+  pipeline: ['loader', 'embedder', 'retriever']
+};
 
 describe('CLI integration with .ragrc.json config fallback', () => {
+  beforeAll(() => {
+    rmSync(TEMP_TEST_DIR, { recursive: true, force: true });
+    mkdirSync(join(TEMP_TEST_DIR, 'src/mocks'), { recursive: true });
+
+    // Assert existence
+    [FIXTURE_PDF, PDF_LOADER_SRC, EMBEDDER_SRC, RETRIEVER_SRC, LLM_SRC].forEach(file => {
+      if (!existsSync(file)) throw new Error(`[FATAL] Missing required fixture: ${file}`);
+    });
+
+    // Copy fixture PDF
+    copyFileSync(FIXTURE_PDF, join(TEMP_TEST_DIR, 'sample.pdf'));
+
+    // Copy mock plugins into temp dir
+    copyFileSync(PDF_LOADER_SRC, join(TEMP_TEST_DIR, 'src/mocks/pdf-loader.js'));
+    copyFileSync(EMBEDDER_SRC, join(TEMP_TEST_DIR, 'src/mocks/openai-embedder.js'));
+    copyFileSync(RETRIEVER_SRC, join(TEMP_TEST_DIR, 'src/mocks/pinecone-retriever.js'));
+    copyFileSync(LLM_SRC, join(TEMP_TEST_DIR, 'src/mocks/openai-llm.js'));
+
+    // Write valid .ragrc.json
+    writeFileSync(FIXTURE_CONFIG, JSON.stringify(FIXTURE_CONFIG_OBJECT, null, 2));
+
+    console.debug('[DEBUG] .ragrc.json contents:\n', JSON.stringify(FIXTURE_CONFIG_OBJECT, null, 2));
+    console.debug('[SETUP] Temp dir:', TEMP_TEST_DIR);
+    console.debug('[SETUP] Contents:', readdirSync(TEMP_TEST_DIR));
+  });
+
+  afterAll(() => {
+    rmSync(TEMP_TEST_DIR, { recursive: true, force: true });
+  });
+
+  test('validates plugin sections contain resolvable names', () => {
+    const config = JSON.parse(readFileSync(FIXTURE_CONFIG, 'utf-8'));
+    ['loader', 'embedder', 'retriever', 'llm'].forEach(type => {
+      expect(typeof config[type]).toBe('object');
+      expect(Object.keys(config[type]).length).toBeGreaterThan(0);
+    });
+  });
+
   test('executes CLI ingest using config fallback', () => {
-    const result = execSync(
-      `node ${CLI_PATH} ingest ./__tests__/fixtures/sample.pdf --loader pdf --embedder openai --retriever pinecone`,
-      { encoding: 'utf-8' }
-    );
-    expect(result).toContain('Ingestion complete');
+    const result = execSync(`node ${CLI_PATH} ingest sample.pdf`, {
+      cwd: TEMP_TEST_DIR,
+      encoding: 'utf-8'
+    });
+    expect(result).toMatch(/Ingestion complete/);
   });
 
   test('executes CLI query using config fallback', () => {
-    const result = execSync(
-      `node ${CLI_PATH} query "What is this test about?" --embedder openai --retriever pinecone --llm openai-gpt-4`,
-      { encoding: 'utf-8' }
-    );
-    // Adjust expectation to check for a known part of the generated answer
-    expect(result).toContain('Generated answer using: Chunk about pine trees');
+    const result = execSync(`node ${CLI_PATH} query "What is this test about?"`, {
+      cwd: TEMP_TEST_DIR,
+      encoding: 'utf-8'
+    });
+    expect(result).toMatch(/Answer:/);
   });
 });

package/__tests__/integration/config/load-config.test.js

@@ -1,52 +1,67 @@
 /**
- * Version: 0.1.0
- * Path: /__tests__/integration/config/load-config.test.js
- * Description: Integration tests for loading and validating .ragrc.json config
+ * Version: 1.1.1
+ * Description: Integration tests for loading and validating .ragrc.json via loadRagConfig()
  * Author: Ali Kahwaji
+ * File: __tests__/integration/config/load-config.test.js
  */
 
 import fs from 'fs';
-import path from 'path';
+import { copyFileSync, mkdirSync, rmSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { loadRagConfig } from '../../../src/config/load-config.js';
 
-const FIXTURE_PATH = path.resolve(process.cwd(), '.ragrc.json');
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = resolve(__filename, '..');
 
-const validConfig = {
-  loader: 'pdf',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  chunk: {
-    strategy: 'semantic',
-    size: 500
-  }
-};
+// Fixture paths
+const FIXTURE_DIR = resolve(__dirname, '../../fixtures');
+const VALID_FIXTURE = join(FIXTURE_DIR, 'valid-ragrc.json');
+const INVALID_FIXTURE = join(FIXTURE_DIR, 'invalid-ragrc.json');
 
-const invalidConfig = {
-  loader: 'pdf',
-  chunk: { size: 'large' } // Missing required keys + invalid type
-};
+// Temp directory used during tests
+const TEMP_DIR = resolve('__tests__', '__temp__', 'load-config');
+const TEMP_CONFIG = join(TEMP_DIR, '.ragrc.json');
 
-describe('loadRagConfig()', () => {
-  afterEach(() => {
-    if (fs.existsSync(FIXTURE_PATH)) {
-      fs.unlinkSync(FIXTURE_PATH);
+// Ensure fixtures are available before copying
+function assertFixturesExist() {
+  const required = [VALID_FIXTURE, INVALID_FIXTURE];
+  required.forEach(file => {
+    if (!existsSync(file)) {
+      throw new Error(`❌ Required test fixture missing: ${file}`);
     }
   });
+}
+
+describe('loadRagConfig()', () => {
+  beforeAll(() => {
+    rmSync(TEMP_DIR, { recursive: true, force: true });
+    mkdirSync(TEMP_DIR, { recursive: true });
+
+    assertFixturesExist();
+  });
+
+  afterAll(() => {
+    rmSync(TEMP_DIR, { recursive: true, force: true });
+  });
 
   test('loads a valid .ragrc.json config file successfully', () => {
-    fs.writeFileSync(FIXTURE_PATH, JSON.stringify(validConfig, null, 2));
-    const result = loadRagConfig();
-    expect(result).toMatchObject(validConfig);
+    copyFileSync(VALID_FIXTURE, TEMP_CONFIG);
+
+    const config = loadRagConfig(TEMP_CONFIG);
+    expect(config).toBeDefined();
+    expect(config.namespace).toBe('cli-config-test');
+    expect(config.loader?.pdf).toBe('./src/mocks/pdf-loader.js');
+    expect(config.pipeline).toEqual(expect.arrayContaining(['loader', 'embedder', 'retriever']));
   });
 
   test('throws validation error for invalid .ragrc.json config', () => {
-    fs.writeFileSync(FIXTURE_PATH, JSON.stringify(invalidConfig, null, 2));
-    expect(() => loadRagConfig()).toThrow(/Invalid config/);
+    copyFileSync(INVALID_FIXTURE, TEMP_CONFIG);
+    expect(() => loadRagConfig(TEMP_CONFIG)).toThrow(/Config validation failed/);
   });
 
   test('throws error if config file does not exist', () => {
-    expect(() => loadRagConfig()).toThrow(/Config file not found/);
+    const NON_EXISTENT = join(TEMP_DIR, 'missing.json');
+    expect(() => loadRagConfig(NON_EXISTENT)).toThrow(/Config file not found/);
   });
 });
-

package/__tests__/unit/config/validate-schema.test.js

@@ -0,0 +1,121 @@
+/**
+ * Version: 1.1.0
+ * Description: Schema validation tests for .ragrc.json using AJV and external fixtures
+ * Author: Ali Kahwaji
+ * File: __tests__/unit/config/validate-schema.test.js
+ */
+
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { validateRagrcSchema, validatePluginSchema } from '../../../src/config/validate-schema.js';
+
+const readFixture = (name) => {
+  const filePath = resolve('__tests__/fixtures',name.replace('.ragrc', '-ragrc'));
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+};
+
+describe('validateRagrcSchema', () => {
+  test('passes with valid structured plugin schema', () => {
+    const config = readFixture('valid-ragrc.json');
+    const result = validateRagrcSchema(config);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toBeUndefined(); // updated: null => undefined
+  });
+
+  test('fails with missing pipeline', () => {
+    const config = {
+      loader: { pdf: './src/mocks/pdf-loader.js' },
+      namespace: 'no-pipeline'
+    };
+    const result = validateRagrcSchema(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          keyword: 'required',
+          params: expect.objectContaining({ missingProperty: 'pipeline' })
+        })
+      ])
+    );
+  });
+  
+  test('fails with non-object plugin sections', () => {
+    const config = {
+      loader: './src/invalid.js', // should be object
+      embedder: { openai: './src/mocks/openai-embedder.js' },
+      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
+      llm: { openai: './src/mocks/openai-llm.js' },
+      pipeline: ['loader'],
+      namespace: 'invalid-section'
+    };
+    const result = validateRagrcSchema(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ instancePath: '/loader' })
+      ])
+    );
+  });
+
+  test('fails with non-string namespace', () => {
+    const config = {
+      loader: { pdf: './src/mocks/pdf-loader.js' },
+      embedder: { openai: './src/mocks/openai-embedder.js' },
+      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
+      llm: { openai: './src/mocks/openai-llm.js' },
+      pipeline: ['loader'],
+      namespace: 12345
+    };
+    const result = validateRagrcSchema(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ instancePath: '/namespace' })
+      ])
+    );
+  });
+});
+
+describe('validatePluginSchema (subset)', () => {
+  test('passes with plugin-only valid structure', () => {
+    const config = {
+      loader: { pdf: './src/mocks/pdf-loader.js' },
+      embedder: { openai: './src/mocks/openai-embedder.js' },
+      retriever: { pinecone: './src/mocks/pinecone-retriever.js' },
+      llm: { openai: './src/mocks/openai-llm.js' }
+    };
+    const result = validatePluginSchema(config);
+    expect(result.valid).toBe(true);
+  });
+
+  test('fails when plugin section is missing', () => {
+    const config = {
+      embedder: { openai: './mock.js' },
+      retriever: { pinecone: './mock.js' },
+      llm: { openai: './mock.js' }
+    };
+    const result = validatePluginSchema(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ instancePath: '', message: expect.stringContaining('must have required property') })
+      ])
+    );
+  });
+
+  test('fails when plugin paths are not strings', () => {
+    const config = {
+      loader: { pdf: 12345 },
+      embedder: { openai: './mock.js' },
+      retriever: { pinecone: './mock.js' },
+      llm: { openai: './mock.js' }
+    };
+    const result = validatePluginSchema(config);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ instancePath: '/loader/pdf' })
+      ])
+    );
+  });
+});

package/__tests__/unit/reranker/llm-reranker.test.js

@@ -1,42 +1,18 @@
 /**
- * Version: 0.1.0
- * Path: /__tests__/unit/reranker/llm-reranker.test.js
- * Description: Unit tests for LLM-based context reranker
- * Author: Ali Kahwaji
+ * File: __tests__/unit/reranker/llm-reranker.test.js
+ * Version: 1.0.0
+ * Description: Validates core behavior of the LLMReranker module
+ * Author: @devilsdev
  */
 
 import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
 
 describe('LLMReranker', () => {
-  const mockDocs = [
-    { text: 'context about math' },
-    { text: 'context about vectors' },
-    { text: 'context about nothing' }
-  ];
-
   test('returns reranked documents based on mock LLM JSON output', async () => {
-    const mockLLM = {
-      async generate() {
-        return '[1, 0, 2]';
-      }
-    };
-    const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('What are vectors?', mockDocs);
-    expect(result.map(d => d.text)).toEqual([
-      'context about vectors',
-      'context about math',
-      'context about nothing'
-    ]);
-  });
-
-  test('gracefully falls back if LLM returns invalid JSON', async () => {
-    const mockLLM = {
-      async generate() {
-        return 'this is not JSON';
-      }
-    };
+    const mockLLM = { async generate() { return '[1, 0, 2]'; } };
+    const docs = [{ text: 'A' }, { text: 'B' }, { text: 'C' }];
     const reranker = new LLMReranker({ llm: mockLLM });
-    const result = await reranker.rerank('Explain.', mockDocs);
-    expect(result.length).toBe(0);
+    const result = await reranker.rerank('What is A?', docs);
+    expect(result.map(d => d.text)).toEqual(['B', 'A', 'C']);
   });
-});
+});

package/__tests__/unit/reranker/reranker.enriched.test.js

@@ -0,0 +1,19 @@
+/**
+ * File: __tests__/unit/reranker/reranker.enriched.test.js
+ * Version: 1.0.0
+ * Description: Tests support for extended document structures
+ * Author: @devilsdev
+ */
+import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
+
+test('supports documents with metadata', async () => {
+    const mockLLM = { async generate() { return '[2, 0, 1]'; } };
+    const docs = [
+      { text: 'One', source: 'alpha' },
+      { text: 'Two', source: 'beta' },
+      { text: 'Three', source: 'gamma' }
+    ];
+    const reranker = new LLMReranker({ llm: mockLLM });
+    const result = await reranker.rerank('Choose the most complete', docs);
+    expect(result[0]).toHaveProperty('source', 'gamma');
+  });

package/__tests__/unit/reranker/reranker.fallback.test.js

@@ -0,0 +1,15 @@
+/**
+ * File: __tests__/unit/reranker/reranker.fallback.test.js
+ * Version: 1.0.0
+ * Description: Validates fallback handling for invalid LLM output
+ * Author: @devilsdev
+ */
+import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
+
+test('gracefully handles invalid LLM output', async () => {
+    const mockLLM = { async generate() { return 'INVALID_JSON'; } };
+    const docs = [{ text: 'X' }, { text: 'Y' }, { text: 'Z' }];
+    const reranker = new LLMReranker({ llm: mockLLM });
+    const result = await reranker.rerank('Prompt?', docs);
+    expect(result.map(d => d.text)).toEqual(['X', 'Y', 'Z']);
+  });

package/__tests__/unit/reranker/reranker.snapshot.test.js

@@ -1,17 +1,15 @@
+/**
+ * File: __tests__/unit/reranker/reranker.snapshot.test.js
+ * Version: 1.0.0
+ * Description: Captures a snapshot baseline of reranked results
+ * Author: @devilsdev
+ */
 import { LLMReranker } from '../../../src/reranker/llm-reranker.js';
 
 test('LLMReranker output snapshot', async () => {
-  const mockLLM = {
-    async generate() {
-      return '[1, 0, 2]';
-    }
-  };
-  const mockDocs = [
-    { text: 'A' },
-    { text: 'B' },
-    { text: 'C' }
-  ];
+  const mockLLM = { async generate() { return '[1, 0, 2]'; } };
+  const mockDocs = [{ text: 'A' }, { text: 'B' }, { text: 'C' }];
   const reranker = new LLMReranker({ llm: mockLLM });
   const result = await reranker.rerank('What is A?', mockDocs);
   expect(result).toMatchSnapshot();
-});
+});