@devilsdev/rag-pipeline-utils 2.0.0 → 2.1.0

package/docs-site/sidebars.js

@@ -2,21 +2,38 @@
 
 /**
  * Sidebar configuration for RAG Pipeline Utils documentation site
- * Generated manually for ordered navigation
+ * Version: 2.0.0
  * Author: Ali Kahwaji
+ * Updated: Structured for modular clarity and DX
  * @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
  */
 
 const sidebars = {
   tutorialSidebar: [
-    'Introduction',
-    'Usage',
-    'CLI',
-    'Architecture',
-    'Evaluation',
-    'Plugins',
-    'FAQ'
-  ]
+    {
+      type: 'category',
+      label: 'Overview',
+      collapsed: false,
+      items: ['Introduction', 'Architecture', 'Tutorials', 'Use-Cases'],
+    },
+    {
+      type: 'category',
+      label: 'Developer Guide',
+      collapsed: false,
+      items: ['Usage', 'CLI', 'Plugins'],
+    },
+    {
+      type: 'category',
+      label: 'Advanced',
+      collapsed: true,
+      items: ['Evaluation', 'FAQ'],
+    },
+    {
+      type: 'link',
+      label: '📰 Blog',
+      href: '/blog',
+    },    
+  ],
 };
 
 export default sidebars;

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

@@ -0,0 +1,31 @@
+// 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

@@ -0,0 +1,34 @@
+/**
+ * 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

@@ -0,0 +1,58 @@
+// 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

@@ -0,0 +1,20 @@
+// 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: '',
+};

package/docs-site/utils/image.js

@@ -0,0 +1,19 @@
+// docs-site/utils/image.js
+import { getPlaiceholder } from 'plaiceholder';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Generates base64 placeholder and img props from local image file
+ * @param {string} imagePath - Relative path to image in /static/img
+ */
+export async function generatePlaceholder(imagePath) {
+  const fullPath = path.join(process.cwd(), 'docs-site', 'static', imagePath);
+  const buffer = await fs.readFile(fullPath);
+  const { base64, img } = await getPlaiceholder(buffer);
+
+  return {
+    ...img,
+    blurDataURL: base64,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-pipeline-utils",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A modular toolkit for building RAG (Retrieval-Augmented Generation) pipelines in Node.js",
   "main": "src/core/create-pipeline.js",
   "bin": {
@@ -17,7 +17,15 @@
     "lint-staged": "lint-staged",
     "postinstall": "husky install",
     "verify:mocks": "node scripts/verify-fixture-mocks.js",
-    "ci": "node scripts/ci-runner.js"
+    "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"
   },
   "lint-staged": {
     "**/*.{js,ts}": [
@@ -48,23 +56,37 @@
     "access": "public"
   },
   "devDependencies": {
+    "@docusaurus/core": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.7.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^9.2.6",
     "@semantic-release/npm": "^11.0.3",
     "@semantic-release/release-notes-generator": "^14.0.3",
+    "@storybook/addon-essentials": "^8.6.12",
+    "@storybook/addon-interactions": "^8.6.12",
+    "@storybook/addon-onboarding": "^8.6.12",
+    "@storybook/addon-webpack5-compiler-swc": "^3.0.0",
+    "@storybook/blocks": "^8.6.12",
+    "@storybook/react": "^8.6.12",
+    "@storybook/react-webpack5": "^8.6.12",
+    "@storybook/test": "^8.6.12",
     "@types/jest": "^29.5.14",
     "codecov": "^3.8.2",
     "cross-env": "^7.0.3",
+    "docusaurus": "^1.14.7",
     "esbuild": "^0.25.2",
     "eslint": "^8.57.1",
+    "eslint-plugin-storybook": "^0.12.0",
     "husky": "^8.0.3",
     "jest": "^29.7.0",
     "lint-staged": "^15.5.1",
     "prettier": "^3.5.3",
+    "prop-types": "^15.8.1",
     "rimraf": "^6.0.1",
     "semantic-release": "^21.1.2",
+    "storybook": "^8.6.12",
     "ts-jest": "^29.3.2"
   },
   "dependencies": {
@@ -77,6 +99,8 @@
     "fast-glob": "^3.3.3",
     "jsdom": "^26.1.0",
     "openai": "^4.93.0",
-    "pino": "^9.6.0"
+    "pino": "^9.6.0",
+    "plaiceholder": "^3.0.0",
+    "sharp": "^0.34.1"
   }
 }

package/scripts/validate-changelog-version.js

@@ -0,0 +1,48 @@
+/**
+ * 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/src/stories/Button.jsx

@@ -0,0 +1,39 @@
+import React from 'react';
+
+import PropTypes from 'prop-types';
+
+import './button.css';
+
+/** Primary UI component for user interaction */
+export const Button = ({
+  primary = false,
+  backgroundColor = null,
+  size = 'medium',
+  label,
+  ...props
+}) => {
+  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
+  return (
+    <button
+      type="button"
+      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
+      style={backgroundColor && { backgroundColor }}
+      {...props}
+    >
+      {label}
+    </button>
+  );
+};
+
+Button.propTypes = {
+  /** Is this the principal call to action on the page? */
+  primary: PropTypes.bool,
+  /** What background color to use */
+  backgroundColor: PropTypes.string,
+  /** How large should the button be? */
+  size: PropTypes.oneOf(['small', 'medium', 'large']),
+  /** Button contents */
+  label: PropTypes.string.isRequired,
+  /** Optional click handler */
+  onClick: PropTypes.func,
+};

package/src/stories/Button.stories.js

@@ -0,0 +1,49 @@
+import { fn } from '@storybook/test';
+
+import { Button } from './Button';
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories#default-export
+export default {
+  title: 'Example/Button',
+  component: Button,
+  parameters: {
+    // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/configure/story-layout
+    layout: 'centered',
+  },
+  // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs
+  tags: ['autodocs'],
+  // More on argTypes: https://storybook.js.org/docs/api/argtypes
+  argTypes: {
+    backgroundColor: { control: 'color' },
+  },
+  // Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked: https://storybook.js.org/docs/essentials/actions#action-args
+  args: { onClick: fn() },
+};
+
+// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
+export const Primary = {
+  args: {
+    primary: true,
+    label: 'Button',
+  },
+};
+
+export const Secondary = {
+  args: {
+    label: 'Button',
+  },
+};
+
+export const Large = {
+  args: {
+    size: 'large',
+    label: 'Button',
+  },
+};
+
+export const Small = {
+  args: {
+    size: 'small',
+    label: 'Button',
+  },
+};