@devilsdev/rag-pipeline-utils 2.1.1 → 2.1.2

package/jest.config.js

@@ -8,9 +8,12 @@
 // jest.config.js
 
 export default {
+  transform: {
+    '^.+\\.[t|j]sx?$': 'babel-jest', // Existing transform for JS files
+    '\\.(png|jpg|jpeg|gif|eot|ttf|woff|woff2)$': 'jest-transform-stub', // this for static files
+  },
   verbose: true,
   testEnvironment: 'node',
-  transform: {},
   collectCoverage: true,
   coverageDirectory: 'coverage',
   moduleFileExtensions: ['js', 'json'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-pipeline-utils",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "A modular toolkit for building RAG (Retrieval-Augmented Generation) pipelines in Node.js",
   "main": "src/core/create-pipeline.js",
   "bin": {
@@ -20,12 +20,13 @@
     "build:docs": "npx docusaurus build docs-site",
     "ci": "node scripts/ci-runner.js",
     "docs:dev": "npx docusaurus start docs-site",
-    "docs:build": "npx docusaurus build docs-site",
-    "docs:deploy": "npx docusaurus deploy docs-site",
     "docs:version": "npx docusaurus docs:version",
-    "docs:serve": "npx docusaurus serve docs-site",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "watch:lqip": "node docs-site/scripts/watch-images.js",
+    "docs:clear": "docusaurus clear --site-dir docs-site",
+    "docs:start": "docusaurus start docs-site",
+    "docs:build": "docusaurus build docs-site",
+    "docs:serve": "docusaurus serve docs-site",
+    "docs:deploy": "docusaurus deploy docs-site"
   },
   "lint-staged": {
     "**/*.{js,ts}": [
@@ -56,6 +57,8 @@
     "access": "public"
   },
   "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
     "@docusaurus/core": "^3.7.0",
     "@docusaurus/preset-classic": "^3.7.0",
     "@semantic-release/changelog": "^6.0.3",
@@ -73,6 +76,7 @@
     "@storybook/react-webpack5": "^8.6.12",
     "@storybook/test": "^8.6.12",
     "@types/jest": "^29.5.14",
+    "babel-jest": "^29.7.0",
     "codecov": "^3.8.2",
     "cross-env": "^7.0.3",
     "docusaurus": "^1.14.7",
@@ -81,6 +85,7 @@
     "eslint-plugin-storybook": "^0.12.0",
     "husky": "^8.0.3",
     "jest": "^29.7.0",
+    "jest-transform-stub": "^2.0.0",
     "lint-staged": "^15.5.1",
     "prettier": "^3.5.3",
     "prop-types": "^15.8.1",
@@ -97,6 +102,7 @@
     "csv-parse": "^5.6.0",
     "dotenv": "^16.5.0",
     "fast-glob": "^3.3.3",
+    "framer-motion": "^12.7.4",
     "jsdom": "^26.1.0",
     "openai": "^4.93.0",
     "pino": "^9.6.0",

package/scripts/fix-mdx-blog-imports.js

@@ -0,0 +1,50 @@
+/**
+ * Version: 1.0.0
+ * Description: Rewrites blog .mdx files to use SSR-safe BlogImage.jsx import
+ * Author: Ali Kahwaji
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const BLOG_DIR = path.resolve('docs-site', 'blog');
+const TARGET_IMPORT = 'import BlogImage from \'../src/components/BlogImage\'';
+const OLD_IMPORT_REGEX = /import\s+BlogImage\s+from\s+['"].+BlogImage[^'"]*['"];/g;
+
+function fixImportInFile(filePath) {
+  let content = fs.readFileSync(filePath, 'utf-8');
+
+  // If already correct, skip
+  if (content.includes(TARGET_IMPORT)) {
+    console.log(`✔️  ${path.basename(filePath)} already uses safe import.`);
+    return;
+  }
+
+  const replaced = content.replace(OLD_IMPORT_REGEX, TARGET_IMPORT);
+
+  if (replaced !== content) {
+    fs.writeFileSync(filePath, replaced);
+    console.log(`✅ Updated: ${path.basename(filePath)}`);
+  } else {
+    // No previous import, insert at top
+    fs.writeFileSync(filePath, `${TARGET_IMPORT}\n\n${content}`);
+    console.log(`➕ Injected import: ${path.basename(filePath)}`);
+  }
+}
+
+function walkDir(dir) {
+  const files = fs.readdirSync(dir);
+  for (const f of files) {
+    const fullPath = path.join(dir, f);
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkDir(fullPath);
+    } else if (f.endsWith('.mdx')) {
+      fixImportInFile(fullPath);
+    }
+  }
+}
+
+console.log('🔍 Scanning MDX blog files...');
+walkDir(BLOG_DIR);
+console.log('🎉 Import rewrite complete.');

package/scripts/fix-mdx-image-imports.js

@@ -0,0 +1,27 @@
+// fix-mdx-image-imports.js
+// Version: 1.0.0
+// Description: Auto-wrap all BlogImage imports with SafeImageWrapper to avoid SSR issues.
+
+import fs from 'fs';
+import path from 'path';
+import glob from 'glob';
+
+const blogDir = path.resolve('docs-site', 'blog');
+
+glob(`${blogDir}/**/*.mdx`, (err, files) => {
+  if (err) throw err;
+
+  files.forEach((file) => {
+    let content = fs.readFileSync(file, 'utf8');
+
+    if (content.includes('from \'@site/src/components/BlogImage\'')) {
+      content = content
+        .replace(/from '@site\/src\/components\/BlogImage'/g, 'from \'@site/src/components/SafeImageWrapper\'')
+        .replace(/<BlogImage/g, '<SafeImageWrapper')
+        .replace(/<\/BlogImage>/g, '</SafeImageWrapper>');
+
+      fs.writeFileSync(file, content, 'utf8');
+      console.log(`✔️ Updated: ${file}`);
+    }
+  });
+});

package/scripts/generate-release-note.js

@@ -0,0 +1,40 @@
+// File: scripts/generate-release-note.js
+/**
+ * Version: 1.2.0
+ * Description: Injects release metadata into markdown template
+ * Author: Ali Kahwaji
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const [,, version, previousTag] = process.argv;
+
+if (!version || !previousTag) {
+  console.error('Usage: node scripts/generate-release-note.js <version> <previousTag>');
+  process.exit(1);
+}
+
+const templatePath = path.join(__dirname, '../.github/release-template.md');
+const outputPath = path.join(__dirname, `../docs-site/blog/${new Date().toISOString().split('T')[0]}-release-${version}.md`);
+
+const template = fs.readFileSync(templatePath, 'utf-8');
+
+// Count contributors
+const contributors = execSync(`git shortlog -sne ${previousTag}..HEAD | wc -l`).toString().trim();
+// Count commits
+const commits = execSync(`git rev-list --count ${previousTag}..HEAD`).toString().trim();
+// ISO date
+const date = new Date().toISOString().split('T')[0];
+
+// Inject into template
+const filled = template
+  .replace(/{{VERSION}}/g, version)
+  .replace(/{{PREVIOUS_TAG}}/g, previousTag)
+  .replace(/{{DATE}}/g, date)
+  .replace(/{{CONTRIBUTORS}}/g, contributors)
+  .replace(/{{COMMITS}}/g, commits);
+
+fs.writeFileSync(outputPath, filled);
+console.log(`✅ Generated release blog: ${outputPath}`);

package/.github/workflows/storybook-deploy.yml

@@ -1,33 +0,0 @@
-# .github/workflows/storybook-deploy.yml
-name: 📘 Deploy Storybook
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'docs-site/src/components/**'
-      - '.storybook/**'
-
-jobs:
-  deploy-storybook:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build Storybook
-        run: npm run build-storybook
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v4
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./storybook-static

package/.storybook/main.js

@@ -1,20 +0,0 @@
-
-
-/** @type { import('@storybook/react-webpack5').StorybookConfig } */
-const config = {
-  "stories": [
-    "../src/**/*.mdx",
-    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
-  ],
-  "addons": [
-    "@storybook/addon-webpack5-compiler-swc",
-    "@storybook/addon-essentials",
-    "@storybook/addon-onboarding",
-    "@storybook/addon-interactions"
-  ],
-  "framework": {
-    "name": "@storybook/react-webpack5",
-    "options": {}
-  }
-};
-export default config;

package/.storybook/preview.js

@@ -1,13 +0,0 @@
-/** @type { import('@storybook/react').Preview } */
-const preview = {
-  parameters: {
-    controls: {
-      matchers: {
-       color: /(background|color)$/i,
-       date: /Date$/i,
-      },
-    },
-  },
-};
-
-export default preview;

package/docs-site/.plaiceholder-cache/img_hero.jpg.json

@@ -1 +0,0 @@
-{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAIAAADwyuo0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAGklEQVR4nGPILapfuW5vblF9blE9A4QD4QMApeANEwX0WNkAAAAASUVORK5CYII="}

package/docs-site/.plaiceholder-cache/img_logo.png.json

@@ -1 +0,0 @@
-{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAT0lEQVR4nAFEALv/AIXNrxKW5b44TKykITGQkA0Atv/dK37FpoIVaGhbSqqbIQAPMjMPAAcXJAAHGTkXJjUQABw3QRQOJT0bFCA3HBUiNRZrJhOUbaRuqQAAAABJRU5ErkJggg=="}

package/docs-site/.storybook/preview.js

@@ -1,8 +0,0 @@
-// .storybook/preview.js
-export const parameters = {
-    layout: 'centered',
-    docs: {
-      title: '🧩 RAG Pipeline UI Components',
-    },
-  };
-  

package/docs-site/blog/2021-08-26-welcome/index.md

@@ -1,28 +0,0 @@
----
-slug: welcome
-title: Welcome
-tags: [facebook, hello, docusaurus]
----
-
-[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
-
-Here are a few tips you might find useful.
-
-<!-- truncate -->
-
-Simply add Markdown files (or folders) to the `blog` directory.
-
-Regular blog authors can be added to `authors.yml`.
-
-The blog post date can be extracted from filenames, such as:
-
-- `2019-05-30-welcome.md`
-- `2019-05-30-welcome/index.md`
-
-A blog post folder can be convenient to co-locate blog post images:
-
-![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
-
-The blog supports tags as well!
-
-**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.

package/docs-site/blog/2025-04-17-release-2.0.md

@@ -1,67 +0,0 @@
----
-slug: release-2-0
-title: Release 2.0.0 – Plugin Contracts, CI Automation, Docs
-authors: [ali]
-tags: [release, changelog]
-description: RAG Pipeline Utils v2.0.0 introduces plugin contract validation, full CI coverage, fixture repairs, and professional Docusaurus docs.
----
-
-We’re thrilled to announce the release of **RAG Pipeline Utils v2.0.0** — a fully modular and developer-focused toolkit for constructing, validating, and managing RAG (Retrieval-Augmented Generation) pipelines.
-
----
-
-## 🚀 Highlights in v2.0.0
-
-### 🔌 Contract-Based Plugin Validation
-
-- Enforces strict interfaces for all core plugin types:
-  - `loader.load()`
-  - `embedder.embed()` and `embedQuery()`
-  - `retriever.store()` and `search()`
-  - `llm.ask()`
-- Includes auto-verification and CLI validation via `scripts/verify-fixture-mocks.js`
-
-### 🧪 Enhanced CI & Git Hooks
-
-- Full GitHub Actions integration:
-  - Lint, test, mock validation, release automation
-- Local enforcement using **Husky** + **validate-changelog-version.js**
-
-### 🧰 Fixture Repair & Auto-Mock Utilities
-
-- Self-healing script: `scripts/repair-fixtures.js`
-- Support for regenerating mocks that align with runtime requirements and CLI tests
-
-### 📘 Developer Documentation
-
-- Professionally published Docusaurus site:
-  - 📚 [Visit Docs](https://devilsdev.github.io/rag-pipeline-utils)
-  - 🧭 Usage, architecture, CLI, plugin extension, and release notes
-- Blog support enabled for continuous release announcements
-
----
-
-## ✨ Why This Matters
-
-This release marks a shift from traditional monolithic RAG stacks to a **fully composable, testable, and CI-validated** toolkit. It was built with long-term developer experience (DX) in mind, emphasizing:
-
-- 📦 **Modularity**: Swap or add plugins without rewriting pipeline logic
-- 🧪 **Test Confidence**: Never publish broken mocks or CI regressions again
-- 🧠 **Scalability**: Suitable for both small prototypes and production pipelines
-- 🛠 **Tooling First**: Includes everything from config loading to evaluation dashboards
-
----
-
-## 📦 Install Now
-
-```bash
-npm install @devilsdev/rag-pipeline-utils
-```
-
----
-
-For upgrade guides, contract schemas, and real-world examples, check out the [official docs](https://devilsdev.github.io/rag-pipeline-utils/docs/Introduction).
-
-🧠 Built for engineers who want **control, clarity, and composability** in their LLM workflows.
-
-— *Ali Kahwaji & RAG Pipeline Utils Contributors*

package/docs-site/blog/2025-04-18-release-2.0.0.md

@@ -1,21 +0,0 @@
----
-slug: release-2-0-0
-title: Release 2.0.0 — Modular RAG Toolkit
-authors: ali
-tags: [release, changelog, RAG, developer-tools]
----
-
-🚀 **Version 2.0.0** is now live on [npm](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)!
-
-This release introduces:
-
-- ✅ Plugin contracts for loaders, embedders, retrievers, LLMs
-- 🧪 Fixture mock verification + CLI validation
-- 🧰 Auto-repair tooling for broken test mocks
-- 📦 Seamless integration with `.ragrc.json` config fallback
-- 📄 Docusaurus documentation & blog support
-- 💡 Modern DX with versioned docs, coverage, CI hooks, changelogs
-
-Explore docs → [devilsdev.github.io/rag-pipeline-utils](https://devilsdev.github.io/rag-pipeline-utils)
-
-📌 Run `npm install @devilsdev/rag-pipeline-utils` to get started.

package/docs-site/blog/2025-04-18-release-v2.1.0.md

@@ -1,13 +0,0 @@
----
-slug: release-v2.1.0
-title: ✨ Version v2.1.0 Released
-authors: [ali]
-tags: [release, changelog]
----
-
-RAG Pipeline Utils vv2.1.0 is now available on NPM!
-
-#### Highlights
-- 🚀 Auto-published blog from GitHub release
-- 📦 Version bump: v2.1.0
-- 📘 See CHANGELOG.md for full details

package/docs-site/docs/components/BlogCardExample.mdx

@@ -1,7 +0,0 @@
-import BlogCard from '@site/src/components/BlogCard';
-
-# 📸 BlogCard Demo
-
-Here's how a typical BlogCard component appears when used with a cached LQIP-enabled image:
-
-<BlogCard title="Composable Pipelines in RAG" image="img_hero.jpg" />

package/docs-site/scripts/generate-placeholders.js

@@ -1,17 +0,0 @@
-// docs-site/scripts/generate-placeholders.js
-import { getPlaiceholder } from 'plaiceholder';
-import fs from 'fs/promises';
-import path from 'path';
-
-const images = ['img/hero.jpg', 'img/logo.png'];
-
-for (const relPath of images) {
-  const fullPath = path.join(process.cwd(), 'docs-site', 'static', relPath);
-  const buffer = await fs.readFile(fullPath);
-  const { base64 } = await getPlaiceholder(buffer);
-  const outPath = relPath.replace(/\//g, '_') + '.json';
-  await fs.writeFile(
-    path.join(process.cwd(), 'docs-site/.plaiceholder-cache', outPath),
-    JSON.stringify({ base64 })
-  );
-}

package/docs-site/scripts/watch-images.js

@@ -1,40 +0,0 @@
-// docs-site/scripts/watch-images.js
-// Version: 1.0.0
-// Description: Watches /static/img for changes and regenerates Plaiceholder LQIP cache
-// Author: Ali Kahwaji
-
-import { generate } from 'plaiceholder';
-import { readdir, readFile, writeFile } from 'fs/promises';
-import chokidar from 'chokidar';
-import path from 'path';
-
-const IMG_DIR = path.resolve('docs-site/static/img');
-const CACHE_DIR = path.resolve('docs-site/.plaiceholder-cache');
-
-async function processImage(file) {
-  const buffer = await readFile(path.join(IMG_DIR, file));
-  const { base64, img } = await generate(buffer);
-
-  const output = {
-    base64,
-    img,
-  };
-
-  const name = file.replace(/\.(jpg|jpeg|png|webp)/i, '');
-  await writeFile(path.join(CACHE_DIR, `img_${name}.json`), JSON.stringify(output, null, 2));
-  console.log(`✅ LQIP generated: img_${name}.json`);
-}
-
-async function run() {
-  const files = await readdir(IMG_DIR);
-  for (const file of files) {
-    if (/\.(jpg|jpeg|png|webp)$/i.test(file)) {
-      await processImage(file);
-    }
-  }
-
-  // Watch for future changes
-  chokidar.watch(IMG_DIR).on('change', processImage).on('add', processImage);
-}
-
-run();

package/docs-site/sidebar-snippet.txt

@@ -1,5 +0,0 @@
-{
-  type: 'link',
-  label: '📰 Blog',
-  href: '/blog',
-},

package/docs-site/src/components/BlogCard.jsx

@@ -1,31 +0,0 @@
-// Version: 1.0.0
-// Description: Blog card with image placeholder using Plaiceholder LQIP
-// Author: Ali Kahwaji
-
-import React from 'react';
-import styles from './BlogCard.module.css';
-import placeholder from '../../.plaiceholder-cache/img_hero.jpg.json'; // ✅ Cached placeholder
-
-export default function BlogCard({ title }) {
-  const { base64, img } = placeholder;
-
-  return (
-    <div className={styles.card}>
-      <img
-        src={img.src}
-        width={img.width}
-        height={img.height}
-        alt={title}
-        loading="lazy"
-        style={{
-          objectFit: 'cover',
-          borderRadius: 12,
-          background: `url(${base64})`,
-          backgroundSize: 'cover',
-          backgroundPosition: 'center',
-        }}
-      />
-      <h3>{title}</h3>
-    </div>
-  );
-}

package/docs-site/src/components/BlogCard.stories.jsx

@@ -1,34 +0,0 @@
-/**
- * Version: 1.0.0
- * File: BlogCard.stories.jsx
- * Description: Storybook entry for BlogCard with image placeholder integration
- * Author: Ali Kahwaji
- */
-
-import React from 'react';
-import BlogCard from './BlogCard';
-
-export default {
-  title: 'Components/BlogCard',
-  component: BlogCard,
-  tags: ['autodocs'],
-  args: {
-    title: 'Composable Pipelines',
-    image: 'img/hero.jpg', // Path relative to /static
-  },
-};
-
-const Template = (args) => <BlogCard {...args} />;
-
-export const Default = Template.bind({});
-
-export const CustomTitle = Template.bind({});
-CustomTitle.args = {
-  title: 'Flexible RAG Components',
-};
-
-export const WithAnotherImage = Template.bind({});
-WithAnotherImage.args = {
-  title: 'LLM Plugin Architecture',
-  image: 'img/social-card.jpg',
-};

package/docs-site/src/components/BlogImage.jsx

@@ -1,58 +0,0 @@
-// docs-site/src/components/BlogImage.jsx
-// Version: 2.0.0
-// Description: Resilient image renderer with LQIP blur fallback from Plaiceholder cache
-// Author: Ali Kahwaji
-
-import React from 'react';
-import PropTypes from 'prop-types';
-import defaultPlaceholder from '../../.plaiceholder-cache/img_hero.jpg.json'; // Default fallback image
-
-/**
- * BlogImage
- * Renders an image using precomputed LQIP placeholders
- *
- * @param {string} srcKey - Cache key (e.g., 'img_logo') without .json
- * @param {string} alt - Image alt text
- * @param {string} [className] - Optional className for custom styling
- * @param {object} [style] - Optional inline styles
- * @returns {JSX.Element}
- */
-export default function BlogImage({ srcKey, alt, className = '', style = {} }) {
-  let imageData;
-
-  try {
-    imageData = require(`../../.plaiceholder-cache/${srcKey}.json`);
-  } catch (e) {
-    console.warn(`⚠️ LQIP not found for ${srcKey}, using fallback.`);
-    imageData = defaultPlaceholder;
-  }
-
-  const { base64, img } = imageData;
-
-  return (
-    <img
-      src={img.src}
-      width={img.width}
-      height={img.height}
-      alt={alt}
-      loading="lazy"
-      className={className}
-      style={{
-        objectFit: 'cover',
-        background: `url(${base64})`,
-        backgroundSize: 'cover',
-        backgroundPosition: 'center',
-        borderRadius: '12px',
-        transition: 'opacity 0.3s ease',
-        ...style,
-      }}
-    />
-  );
-}
-
-BlogImage.propTypes = {
-  srcKey: PropTypes.string.isRequired,
-  alt: PropTypes.string.isRequired,
-  className: PropTypes.string,
-  style: PropTypes.object,
-};

package/docs-site/src/components/BlogImage.stories.jsx

@@ -1,20 +0,0 @@
-// Version: 1.0.0
-// Description: Storybook story for BlogImage component
-// Author: Ali Kahwaji
-
-import React from 'react';
-import BlogImage from '../BlogImage';
-
-export default {
-  title: 'Components/BlogImage',
-  component: BlogImage,
-};
-
-const Template = (args) => <BlogImage {...args} />;
-
-export const Default = Template.bind({});
-Default.args = {
-  srcKey: 'img_hero',
-  alt: 'Default placeholder image',
-  className: '',
-};