@devilsdev/rag-pipeline-utils 2.1.5 → 2.1.8

package/scripts/repair-fixtures.js

@@ -1,30 +0,0 @@
-/**
- * Version: 1.0.0
- * Description: Auto-repairs mock plugin fixtures for integration tests
- * Author: Ali Kahwaji
- */
-
-import { mkdirSync, copyFileSync, existsSync } from 'fs';
-import { resolve, join } from 'path';
-
-const MOCKS = [
-  'pdf-loader.js',
-  'openai-embedder.js',
-  'pinecone-retriever.js',
-  'openai-llm.js'
-];
-
-const SRC_FIXTURES = resolve('__tests__/fixtures/src/mocks');
-const DEST_FIXTURES = resolve('__tests__/__temp__/cli-config-fallback/src/mocks');
-
-mkdirSync(DEST_FIXTURES, { recursive: true });
-
-MOCKS.forEach((file) => {
-  const src = join(SRC_FIXTURES, file);
-  const dest = join(DEST_FIXTURES, file);
-  if (!existsSync(src)) throw new Error(`[FIXTURE MISSING] ${src}`);
-  copyFileSync(src, dest);
-  console.log(`[COPIED] ${file}`);
-});
-
-console.log('✅ Fixture mocks successfully repaired.');

package/scripts/setup.js

@@ -1,31 +0,0 @@
-/**
- * Version: 1.1.0
- * Description: Test setup script to ensure fixtures exist and validate mocks before running tests.
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-
-// Resolve __dirname in ES module scope
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const fixturePath = path.resolve(__dirname, '../__tests__/fixtures/sample.pdf');
-
-// Ensure PDF test fixture
-if (!fs.existsSync(fixturePath)) {
-  fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
-  fs.writeFileSync(fixturePath, 'Dummy PDF content for test');
-  console.log('[setup] Created sample.pdf fixture');
-}
-
-// Validate plugin fixture presence
-try {
-  execSync('node ./scripts/verify-fixtures.js', { stdio: 'inherit' });
-} catch (err) {
-  console.error('[setup] Fixture verification failed. Please check missing mocks.');
-  process.exit(1);
-}

package/scripts/sync-labels.js

@@ -1,71 +0,0 @@
-/**
- * Version: 1.1.0
- * Description: Syncs GitHub labels based on roadmap-labels.yml; updates existing, creates missing.
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import yaml from 'js-yaml';
-import { Octokit } from '@octokit/rest';
-
-const GITHUB_TOKEN = process.env.GITHUB_TOKEN;
-const REPO = process.env.GITHUB_REPOSITORY;
-
-if (!GITHUB_TOKEN || !REPO) {
-  console.error('❌ GITHUB_TOKEN or GITHUB_REPOSITORY not defined in environment.');
-  process.exit(1);
-}
-
-const [owner, repo] = REPO.split('/');
-const octokit = new Octokit({ auth: GITHUB_TOKEN });
-
-const LABELS_FILE = path.join('.github', 'roadmap-labels.yml');
-
-function loadLabelsFromYAML(filePath) {
-  try {
-    const file = fs.readFileSync(filePath, 'utf8');
-    return yaml.load(file);
-  } catch (err) {
-    console.error('❌ Failed to load roadmap-labels.yml:', err);
-    process.exit(1);
-  }
-}
-
-async function syncLabels() {
-  const labels = loadLabelsFromYAML(LABELS_FILE);
-  const existingLabels = await octokit.paginate(octokit.rest.issues.listLabelsForRepo, {
-    owner,
-    repo,
-  });
-
-  for (const label of labels) {
-    const existing = existingLabels.find(l => l.name === label.name);
-
-    try {
-      if (existing) {
-        console.log(`🔁 Updating label: ${label.name}`);
-        await octokit.rest.issues.updateLabel({
-          owner,
-          repo,
-          name: label.name,
-          color: label.color,
-          description: label.description,
-        });
-      } else {
-        console.log(`➕ Creating label: ${label.name}`);
-        await octokit.rest.issues.createLabel({
-          owner,
-          repo,
-          name: label.name,
-          color: label.color,
-          description: label.description,
-        });
-      }
-    } catch (err) {
-      console.error(`❌ Failed to process label: ${label.name}`, err.message);
-    }
-  }
-}
-
-syncLabels();

package/scripts/sync-roadmap-labels.js

@@ -1,21 +0,0 @@
-// scripts/sync-roadmap-labels.js
-
-/**
- * Version: 1.1.0
- * Description: Sync roadmap labels and issues
- * Author: Ali Kahwaji
- */
-
-import { ensureRoadmapLabels } from './ensure-roadmap-labels.js';
-import { createRoadmapIssues } from './create-roadmap-issues.js';
-
-const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
-const token = process.env.GITHUB_TOKEN;
-
-if (!token) {
-  console.error('❌ Missing GITHUB_TOKEN');
-  process.exit(1);
-}
-
-await ensureRoadmapLabels({ token, owner, repo });
-await createRoadmapIssues({ token, owner, repo });

package/scripts/tag-release.js

@@ -1,64 +0,0 @@
-/**
- * Version: 2.0.0
- * Description: Tags release, updates changelog, optionally opens blog preview
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { execSync } from 'child_process';
-import readline from 'readline';
-
-const VERSION = process.argv[2];
-const PREVIEW = process.argv.includes('--preview');
-
-if (!VERSION) {
-  console.error('❌ Usage: node release-tag.js <version> [--preview]');
-  process.exit(1);
-}
-
-const tag = `v${VERSION}`;
-const blogPath = path.join('docs-site', 'blog');
-
-// Step 1: Run changelog injection
-execSync(`node scripts/generate-release-note.js ${VERSION}`, { stdio: 'inherit' });
-
-// Step 2: Find generated blog file
-const date = new Date().toISOString().split('T')[0];
-const file = path.join(blogPath, `${date}-release-${tag}.md`);
-
-if (!fs.existsSync(file)) {
-  console.error(`❌ Blog post not generated: ${file}`);
-  process.exit(1);
-}
-
-// Step 3: Preview if enabled
-if (PREVIEW) {
-  const editor = process.env.EDITOR || 'code'; // fallback to VS Code
-  try {
-    execSync(`${editor} ${file}`, { stdio: 'inherit' });
-  } catch (err) {
-    console.warn('⚠️ Failed to open in editor. Please review manually:', file);
-  }
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  rl.question(`✅ Ready to commit and push ${tag}? (y/n): `, (answer) => {
-    rl.close();
-    if (answer.toLowerCase() !== 'y') {
-      console.log('❌ Aborted. No tag pushed.');
-      process.exit(0);
-    }
-    finalizeRelease();
-  });
-} else {
-  finalizeRelease();
-}
-
-// Final tagging + push
-function finalizeRelease() {
-  execSync(`git add CHANGELOG.md ${file}`);
-  execSync(`git commit -m "release: v${VERSION}"`);
-  execSync(`git tag ${tag}`);
-  execSync('git push && git push --tags');
-  console.log(`🎉 Release ${tag} published and blog post staged!`);
-}

package/scripts/test-global-setup.js

@@ -1,18 +0,0 @@
-// __tests__/setup/global.js
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// __dirname polyfill for ESM
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const pdfPath = path.resolve(__dirname, '../fixtures/sample.pdf');
-
-// Ensure the fixtures directory exists
-fs.mkdirSync(path.dirname(pdfPath), { recursive: true });
-
-// Create a minimal valid PDF file if it doesn't exist
-if (!fs.existsSync(pdfPath)) {
-  fs.writeFileSync(pdfPath, '%PDF-1.4\n%EOF');
-}

package/scripts/validate-changelog-version.js

@@ -1,48 +0,0 @@
-/**
- * Version: 1.1.0
- * Description: Ensures CHANGELOG.md contains the current version and auto-corrects format if needed.
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json')));
-const version = pkg.version;
-const changelogPath = path.resolve(__dirname, '../CHANGELOG.md');
-
-let changelog = fs.readFileSync(changelogPath, 'utf-8');
-
-// Step 1: Normalize invalid headings like "# [2.0.0](...)"
-const normalized = changelog.replace(/^# \[([0-9]+\.[0-9]+\.[0-9]+)\]\([^)]+\)/gm, (match, v) => {
-  const today = new Date().toISOString().split('T')[0];
-  return `## [${v}] - ${today}`;
-});
-
-// Step 2: Update file if normalization occurred
-if (normalized !== changelog) {
-  fs.writeFileSync(changelogPath, normalized);
-  console.log(`🛠️  CHANGELOG.md heading normalized for version ${version}`);
-  changelog = normalized;
-
-  // Auto-stage if in git project (Husky compatibility)
-  try {
-    execSync(`git add ${changelogPath}`);
-    console.log('CHANGELOG.md staged after correction');
-  } catch {
-    // Non-fatal
-  }
-}
-
-// Step 3: Validate presence of correct heading
-const headingPattern = new RegExp(`^## \\[${version}\\]`, 'm');
-if (!headingPattern.test(changelog)) {
-  throw new Error(`❌ CHANGELOG.md does not contain a properly formatted entry for version ${version}`);
-}
-
-console.log(`✅ CHANGELOG.md contains a valid entry for version ${version}`);

package/scripts/verify-fixture-mocks.js

@@ -1,45 +0,0 @@
-/**
- * Version: 1.0.0
- * Description: Verifies that plugin mock implementations expose required methods
- * Author: Ali Kahwaji
- */
-
-import { readdirSync, statSync } from 'fs';
-import { resolve, join, extname } from 'path';
-import { pathToFileURL } from 'url';
-
-const MOCKS_DIR = resolve('__tests__/fixtures/src/mocks');
-
-const pluginContracts = {
-  'openai-embedder.js': ['embed', 'embedQuery'],
-  'openai-llm.js': ['ask'],
-  'pdf-loader.js': ['load'],
-  'pinecone-retriever.js': ['store', 'search'],
-};
-
-const failures = [];
-
-for (const file of readdirSync(MOCKS_DIR)) {
-  const fullPath = join(MOCKS_DIR, file);
-  const isFile = statSync(fullPath).isFile();
-  if (!isFile || extname(file) !== '.js') continue;
-
-  const expectedMethods = pluginContracts[file];
-  if (!expectedMethods) continue;
-
-  const mod = await import(pathToFileURL(fullPath).href);
-  const plugin = new mod.default();
-
-  for (const method of expectedMethods) {
-    if (typeof plugin[method] !== 'function') {
-      failures.push(`❌ ${file} failed: [${file}] missing method: ${method}`);
-    }
-  }
-}
-
-if (failures.length > 0) {
-  failures.forEach(msg => console.error(msg));
-  process.exit(1);
-} else {
-  console.log('✅ All plugin mocks verified.');
-}

package/scripts/verify-fixtures.js

@@ -1,36 +0,0 @@
-/**
- * Version: 1.0.0
- * Description: Script to verify presence of all expected fixture plugins before running integration tests.
- * Author: Ali Kahwaji
- * File: scripts/verify-fixtures.js
- */
-
-import { existsSync } from 'fs';
-import { resolve } from 'path';
-
-const REQUIRED_FIXTURES = [
-  '__tests__/fixtures/sample.pdf',
-  '__tests__/fixtures/.ragrc.json',
-  '__tests__/fixtures/src/mocks/pdf-loader.js',
-  '__tests__/fixtures/src/mocks/openai-embedder.js',
-  '__tests__/fixtures/src/mocks/pinecone-retriever.js',
-  '__tests__/fixtures/src/mocks/openai-llm.js'
-];
-
-let missing = [];
-for (const file of REQUIRED_FIXTURES) {
-  const fullPath = resolve(file);
-  if (!existsSync(fullPath)) {
-    missing.push(fullPath);
-  }
-}
-
-if (missing.length) {
-  console.error('[ERROR] Missing test fixture files:');
-  for (const f of missing) {
-    console.error(' -', f);
-  }
-  process.exit(1);
-} else {
-  console.log('[OK] All fixture files are present.');
-}

package/server.js

@@ -1,31 +0,0 @@
-/**
- * Version: 0.1.0
- * Path: /server.js
- * Description: Local static server for serving evaluation dashboard
- * Author: Ali Kahwaji
- */
-
-import express from 'express';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const app = express();
-const port = process.env.PORT || 3000;
-
-// Serve evaluation results statically
-app.use('/results', express.static(path.join(__dirname, '__tests__/fixtures')));
-
-// Serve public frontend assets
-app.use(express.static(path.join(__dirname, 'public')));
-
-// Fallback to index.html
-app.get('*', (req, res) => {
-  res.sendFile(path.join(__dirname, 'public/index.html'));
-});
-
-app.listen(port, () => {
-  console.log(` Dashboard running at http://localhost:${port}`);
-});

package/src/config/load-config.js

@@ -1,33 +0,0 @@
-/**
- * Version: 1.1.0
- * Description: Loads validated .ragrc.json config from disk
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { validateRagrcSchema } from './validate-schema.js';
-import { logger } from '../utils/logger.js';
-
-/**
- * Loads and validates a RAG config file.
- * @param {string} configPath - Absolute path to .ragrc.json
- * @returns {object} Parsed config object
- * @throws {Error} If file is missing or invalid
- */
-export function loadRagConfig(configPath) {
-  if (!fs.existsSync(configPath)) {
-    throw new Error(`Config file not found: ${configPath}`);
-  }
-
-  const raw = fs.readFileSync(configPath, 'utf-8');
-  const parsed = JSON.parse(raw);
-
-  const result = validateRagrcSchema(parsed);
-  if (!result.valid) {
-    logger.error({ errors: result.errors }, 'Invalid .ragrc.json schema');
-    throw new Error('Config validation failed');
-  }
-
-  return parsed;
-}

package/src/config/load-plugin-config.js

@@ -1,56 +0,0 @@
-/**
- * Version: 1.1.1
- * Description: Dynamic plugin loader with direct type:name registry mapping
- * Author: Ali Kahwaji
- */
-
-import fs from 'fs';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import registry from '../core/plugin-registry.js';
-import { validatePluginSchema } from './validate-schema.js';
-import { logger } from '../utils/logger.js';
-
-/**
- * Loads plugins from validated config path and registers them.
- * @param {string} configPath
- */
-export async function loadPluginsFromJson(configPath) {
-  if (!fs.existsSync(configPath)) {
-    throw new Error(`Plugin config missing: ${configPath}`);
-  }
-
-  const raw = fs.readFileSync(configPath, 'utf-8');
-  const config = JSON.parse(raw);
-
-  const validation = validatePluginSchema(config);
-  if (!validation.valid) {
-    logger.error({ errors: validation.errors }, 'Invalid plugin config');
-    throw new Error('Plugin config validation failed');
-  }
-
-  for (const [type, namedPlugins] of Object.entries(config)) {
-    if (!['loader', 'embedder', 'retriever', 'llm'].includes(type)) continue;
-
-    for (const [name, relPath] of Object.entries(namedPlugins)) {
-      const absPath = path.resolve(path.dirname(configPath), relPath);
-      const fileUrl = pathToFileURL(absPath).href;
-
-      try {
-        const mod = await import(fileUrl);
-        const PluginClass = mod?.default;
-        if (typeof PluginClass !== 'function') {
-          throw new Error(`Invalid export in plugin [${type}:${name}] at ${absPath}`);
-        }
-
-        const instance = new PluginClass();
-        registry.register(type, name, instance);
-
-        logger.info({ type, name }, `Registered plugin: ${type}:${name}`);
-      } catch (err) {
-        logger.error({ type, name, err }, `Failed to register plugin [${type}:${name}]`);
-        throw err;
-      }
-    }
-  }
-}

package/src/config/validate-plugin-schema.js

@@ -1,28 +0,0 @@
-/**
- * Version: 0.1.0
- * Description: Schema validator for plugin.config.json
- * Author: Ali Kahwaji
- */
-
-export function validatePluginSchema(config) {
-    const validTypes = ['loader', 'embedder', 'retriever', 'llm'];
-    const errors = [];
-  
-    for (const type of Object.keys(config)) {
-      if (!validTypes.includes(type)) {
-        errors.push(`Unknown plugin type: ${type}`);
-        continue;
-      }
-      for (const [name, modulePath] of Object.entries(config[type])) {
-        if (typeof name !== 'string' || typeof modulePath !== 'string') {
-          errors.push(`Invalid plugin definition for type "${type}" and name "${name}"`);
-        }
-      }
-    }
-  
-    return {
-      valid: errors.length === 0,
-      errors
-    };
-  }
-  

package/src/config/validate-schema.js

@@ -1,107 +0,0 @@
-/**
- * Version: 1.3.0
- * Description: AJV-powered validators for .ragrc.json full config and plugin-only structure
- * Author: Ali Kahwaji
- * File: /src/config/validate-schema.js
- */
-
-import Ajv from 'ajv';
-
-/**
- * Full .ragrc.json schema (used in load-config.js)
- */
-const ragrcSchema = {
-  type: 'object',
-  required: ['loader', 'embedder', 'retriever', 'llm', 'namespace', 'pipeline'],
-  properties: {
-    loader: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    embedder: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    retriever: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    llm: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    namespace: {
-      type: 'string',
-      minLength: 1
-    },
-    pipeline: {
-      type: 'array',
-      items: {
-        type: 'string',
-        enum: ['loader', 'embedder', 'retriever']
-      },
-      minItems: 1,
-      uniqueItems: true
-    }
-  },
-  additionalProperties: false
-};
-
-/**
- * Minimal plugin-only schema (used in load-plugin-config.js)
- */
-const pluginSchema = {
-  type: 'object',
-  required: ['loader', 'embedder', 'retriever', 'llm'],
-  properties: {
-    loader: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    embedder: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    retriever: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    },
-    llm: {
-      type: 'object',
-      minProperties: 1,
-      additionalProperties: { type: 'string' }
-    }
-  },
-  additionalProperties: true // allow namespace, pipeline, etc.
-};
-
-/**
- * Validates the full .ragrc.json config structure
- * @param {object} config
- * @returns {{ valid: boolean, errors?: any[] }}
- */
-export function validateRagrcSchema(config) {
-  const ajv = new Ajv({ allErrors: true });
-  const validate = ajv.compile(ragrcSchema);
-  const valid = validate(config);
-  return valid ? { valid: true } : { valid: false, errors: validate.errors };
-}
-
-/**
- * Validates a plugin-only structure (for runtime plugin loading)
- * @param {object} config
- * @returns {{ valid: boolean, errors?: any[] }}
- */
-export function validatePluginSchema(config) {
-  const ajv = new Ajv({ allErrors: true });
-  const validate = ajv.compile(pluginSchema);
-  const valid = validate(config);
-  return valid ? { valid: true } : { valid: false, errors: validate.errors };
-}