@devilsdev/rag-pipeline-utils 2.1.7 → 2.1.8

package/scripts/manual-test-checklist.md

@@ -1,90 +0,0 @@
-# ✅ Manual Test Checklist for RAG Pipeline Utils
-
-This document outlines manual test points for validating roadmap automation, documentation builds, CI/CD, blog sync, and changelog generation.
-
----
-
-## 1. 🔄 Roadmap Sync + Label Automation
-
-| ✅ Task | Command or Trigger | Notes |
-|--------|--------------------|-------|
-| Sync `PROJECT_ROADMAP.md` to GitHub Issues | `git push` or `workflow_dispatch` for `sync-roadmap.yml` | Issues, assignees, labels should match |
-| Auto-create missing roadmap labels | `sync-roadmap.yml` step: `ensure-roadmap-labels.js` | Should not error even if labels exist |
-| Label updates reflect correct color & description | Rerun roadmap sync | Existing labels should be updated |
-| Roadmap issue closed on ✅ Done status | Modify `PROJECT_ROADMAP.md` status and sync | Corresponding issue should be auto-closed |
-
----
-
-## 2. 🧭 CLI + Manual Utilities
-
-| ✅ Task | Command | Notes |
-|--------|---------|-------|
-| Create roadmap issues manually | `node scripts/create-roadmap-issues.js` | Creates GitHub Issues |
-| Ensure labels via CLI | `node scripts/ensure-roadmap-labels.js` | Must succeed with idempotency |
-| Generate changelog and preview | `npm run release:tag` | Prompt for tag + generate CHANGELOG |
-| Preview auto-generated blog post | Preview `.md` file in `/docs-site/blog` before push |
-
----
-
-## 3. 📚 Docs + Deployment
-
-| ✅ Task | Command | Notes |
-|--------|---------|-------|
-| Build Docusaurus | `npm run docs:build` | No broken links, light/dark theme OK |
-| Deploy to GitHub Pages | `npm run docs:deploy` | Check rendered site at `/rag-pipeline-utils` |
-| Verify CHANGELOG link works | Test `/blog` page post link to `CHANGELOG.md` |
-
----
-
-## 4. 🧪 CI/CD Validation
-
-| ✅ Task | Check | Notes |
-|--------|-------|-------|
-| CI Lint + Test runs | ✅ `ci.yml` | Lint passes, all Jest tests green |
-| Docs CI runs correctly | ✅ `docs-ci.yml` | No script missing error, build valid |
-| Docs auto-deploys on push | ✅ `docs-deploy.yml` | Publishes to GitHub Pages |
-
----
-
-## 5. 🏷 GitHub Releases
-
-| ✅ Task | Trigger | Notes |
-|--------|---------|-------|
-| Generate blog post on release | Publish GitHub tag | `publish-release-blog.yml` should commit new `.md` |
-| Auto-fill blog content | From `CHANGELOG.md` and compare link | Author + commit stats populated |
-
----
-
-## 6. 🛡 Release Gatekeeping & Metadata
-
-| ✅ Task | Outcome | Notes |
-|--------|---------|-------|
-| Badge renders in README | `![Release Review Passed]` | Should point to last workflow run |
-| Protected branch config for PRs | Status check on `release:review` | Prevents push without passing review |
-
----
-
-## 7. 🧾 Filesystem and Cleanup
-
-| ✅ Task | Notes |
-|--------|-------|
-| `src/stories/` removed | No Storybook assets in GH Pages |
-| `postcss.config.cjs` & `tailwind.config.js` removed | Confirm no broken styling or build errors |
-
----
-
-## 🔁 Optional Manual Commands
-
-```bash
-# Sync roadmap manually
-node scripts/create-roadmap-issues.js
-
-# Ensure roadmap labels
-node scripts/ensure-roadmap-labels.js
-
-# Trigger changelog + blog post flow
-npm run release:tag
-
-# Build and deploy docs
-npm run docs:build && npm run docs:deploy
-```

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
-    };
-  }
-