@devilsdev/rag-pipeline-utils 2.0.0 → 2.0.1

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

@@ -0,0 +1,36 @@
+name: Deploy Docusaurus to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+                - 'docs-site/**'
+                - 'blog/**'
+                - 'sidebars.js'
+                - 'docusaurus.config.js'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      - name: ⚙️ Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🛠️ Build static site
+        run: npm run build:docs
+
+      - name: 🚀 Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs-site/build
+              
+          

package/.github/workflows/publish-release-blog.yml

@@ -0,0 +1,51 @@
+# .github/workflows/publish-release-blog.yml
+# Version: 1.0.0
+# Description: Auto-publish blog post from CHANGELOG or prepared .md after NPM release
+# Author: Ali Kahwaji
+
+name: ✨ Publish Release Blog Post
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish-blog-post:
+    name: Generate & Commit Blog Post
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: ⬇️ Checkout code
+        uses: actions/checkout@v4
+
+      - name: 🔧 Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: ✏️ Generate blog post
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          DATE=$(date +'%Y-%m-%d')
+          FILE="docs-site/blog/${DATE}-release-${VERSION}.md"
+
+          echo "---" > $FILE
+          echo "slug: release-${VERSION}" >> $FILE
+          echo "title: ✨ Version ${VERSION} Released" >> $FILE
+          echo "authors: [ali]" >> $FILE
+          echo "tags: [release, changelog]" >> $FILE
+          echo "---" >> $FILE
+          echo >> $FILE
+
+          echo "RAG Pipeline Utils v${VERSION} is now available on NPM!" >> $FILE
+          echo >> $FILE
+          echo "#### Highlights" >> $FILE
+          echo "- Automated blog generation on GitHub releases" >> $FILE
+          echo "- Version bump: ${VERSION}" >> $FILE
+          echo "- Ensure CHANGELOG.md is synced" >> $FILE
+
+      - name: 📋 Commit blog post
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs(blog): add release post for ${{ github.ref_name }}"
+          file_pattern: "docs-site/blog/*.md"

package/.husky/pre-commit

@@ -3,3 +3,4 @@
 
 npm run validate-fixtures && npm run lint
 npx lint-staged
+node scripts/validate-changelog-version.js

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-# [2.0.0](https://github.com/DevilsDev/rag-pipeline-utils/compare/v1.0.1...v2.0.0) (2025-04-17)
+## [2.0.1](https://github.com/DevilsDev/rag-pipeline-utils/compare/v2.0.0...v2.0.1) (2025-04-17)
+
+
+### Bug Fixes
+
+* add @docusaurus/preset-classic to enable CI builds ([ed5e771](https://github.com/DevilsDev/rag-pipeline-utils/commit/ed5e771f919face4693a6a7abfed4cf0fe1325ca))
+
+## [2.0.0] - 2025-04-17 (2025-04-17)
 
 
 ### Bug Fixes

package/README.md

@@ -1,117 +1,146 @@
 # @DevilsDev/rag-pipeline-utils
 
+
+
+# RAG Pipeline Utils
+
+> Modular utilities for building Retrieval-Augmented Generation (RAG) pipelines, with CI-verified plugin contracts and mockable interfaces.
+
 [![CI](https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/DevilsDev/rag-pipeline-utils/actions)
 [![codecov](https://codecov.io/gh/DevilsDev/rag-pipeline-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/DevilsDev/rag-pipeline-utils)
 ![Release](https://img.shields.io/github/v/release/DevilsDev/rag-pipeline-utils?label=release)
+![License](https://img.shields.io/github/license/devilsdev/rag-pipeline-utils)
 
-**A modular Node.js toolkit for building RAG (Retrieval-Augmented Generation) pipelines with clean abstractions, pluggable components, and scalable architecture.**
+## Description
 
----
+`@devilsdev/rag-pipeline-utils` provides a clean, extensible, and test-friendly foundation for constructing robust RAG pipelines using a plugin-based architecture. It enables developers to plug in their own document loaders, embedders, retrievers, and LLMs via configuration, and includes a CLI, mock contract verification, schema validation, and test harnesses to ensure production-readiness.
 
-## Features
+## Key Features
 
-- ✅ Plugin-based architecture for RAG pipelines
-- ✅ Embedding + retrieval abstraction
-- ✅ Vector DB integrations (e.g., Pinecone)
-- ✅ Modular document loaders (PDF, HTML, Markdown, CSV, Directory)
-- ✅ CLI with `.ragrc.json` config fallback
-- ✅ Retry, backoff, and logging built-in
-- ✅ Reranker support and evaluation tooling
-- ✅ React dashboard for evaluation results
+- **Plugin Contracts**: Runtime and CI verification of plugin interfaces (loader, embedder, retriever, llm).
+- **CLI Support**: Easily run `ingest` and `query` commands using `.ragrc.json` configuration.
+- **Test Fixtures**: Snapshot, fallback, and structured reranker validation.
+- **Schema Enforcement**: `.ragrc.json` schema validation to catch config issues early.
+- **Mock Repair Utilities**: Auto-fix for missing or broken mock implementations.
+- **Modular Design**: Drop-in plugin support using custom class-based implementations.
 
----
+## Benefits of This Modular Design
+
+- **Extensibility**: Developers can inject their own loader, retriever, or LLM logic without modifying the core.
+- **Testability**: Mocks and CI tools validate contract adherence for reliable test coverage.
+- **Decoupling**: Each plugin can be independently implemented and swapped in via `.ragrc.json`.
+- **CI Resilience**: The CI pipeline includes linting, contract verification, and test coverage enforcement.
 
 ## Installation
 
 ```bash
-npm install @yourorg/rag-pipeline-utils
+npm install @devilsdev/rag-pipeline-utils
 ```
 
----
+## Basic Usage
 
-## Usage
+1. Create a `.ragrc.json` config:
 
-```js
-import { createRagPipeline } from '@yourorg/rag-pipeline-utils';
+```json
+{
+  "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": "demo-namespace",
+  "pipeline": ["loader", "embedder", "retriever"]
+}
+```
 
-const rag = createRagPipeline({
-  loader: 'markdown',
-  embedder: 'openai',
-  retriever: 'pinecone',
-  llm: 'openai-gpt-4',
-  useReranker: true
-});
+2. Run an ingestion:
 
-const answer = await rag.query('What is a vector database?');
-console.log(answer);
+```bash
+node bin/cli.js ingest ./docs/sample.pdf
 ```
 
----
-
-## Testing
+3. Run a query:
 
 ```bash
-npm test
+node bin/cli.js query "What is in the document?"
 ```
 
----
+## Plugin Contracts
+
+Each plugin must implement the following interface:
+
+| Type      | Required Methods                            |
+| --------- | ------------------------------------------- |
+| loader    | `load(filePath)`                          |
+| embedder  | `embed(documents)`, `embedQuery(query)` |
+| retriever | `store(vectors)`, `search(queryVector)` |
+| llm       | `ask(prompt)`                             |
+
+## Folder Structure
+
+```text
+/project-root
+├── /src
+│   ├── /routes
+│   ├── /services
+│   ├── /utils
+│   └── app.js
+├── /scripts
+│   ├── setup.js
+│   ├── ci-runner.js
+│   └── repair-fixtures.js
+├── /__tests__
+│   ├── /fixtures
+│   ├── /unit
+│   ├── /integration
+├── /public
+├── README.md
+├── USE_CASES.md
+├── CHANGELOG.md
+└── .env.example
+```
 
-## CLI
 
-```bash
-rag-pipeline ingest ./docs/my.pdf --loader pdf
-rag-pipeline query "Explain RAG pipelines" --llm openai-gpt-4
-rag-pipeline evaluate ./fixtures/sample-eval-dataset.json
-rag-pipeline rerank "Explain embeddings" --retriever pinecone
-```
 
-Supports `.ragrc.json` fallback configuration:
+## Why Use This?
 
-```json
-{
-  "loader": "directory",
-  "embedder": "openai",
-  "retriever": "pinecone",
-  "llm": "openai-gpt-4",
-  "useReranker": true
-}
-```
+- **Developer Experience**: Fast iteration, full contract CI
+- **Pluggable Design**: Swap in your stack (OpenAI, Pinecone, Langchain, etc.)
+- **Minimal & Modular**: Clean separation of concerns
+- **Prod-ready**: 100% test coverage, schema validation, CLI control
 
----
 
-## Project Structure
 
-```
-/src
-  ├── core/           # Pipeline + registry
-  ├── loader/         # Loaders for md, html, csv, dir
-  ├── reranker/       # LLM-based context reranker
-  ├── evaluate/       # Scoring, batch QA evaluation
-  ├── utils/          # Logger, retry, schema
-/bin/cli.js           # CLI entrypoint
-/__tests__/           # Unit, integration, snapshot tests
-/public/              # Evaluation dashboard (React)
-.github/workflows/ci.yml # CI config
-```
+## Use Cases
 
----
+Explore real-world DevX-focused examples in [USE_CASES.md](./USE_CASES.md), including:
 
-## Evaluation Dashboard
+- Mock-driven plugin TDD
+- CI-based interface validation
+- Multivendor ingestion and search
+- Runtime swap of LLM, retrievers, or embedders
+- Bootstrap pipelines with auto-repairable defaults
 
-```bash
-node server.js
-```
 
-Visit: [http://localhost:3000](http://localhost:3000) → Visualizes metrics, BLEU/ROUGE, pass rate.
 
----
+## Contributing
+
+We welcome contributions via PRs, especially new mock providers, validation helpers, and runtime extensions. Please follow the test + CI conventions before submitting.
+
+
 
 ## License
 
-Apache-2.0
+This project is licensed under the **GNU GPL v3.0** License - see the [LICENSE](./LICENSE) file for details.
 
 ---
 
-## 👤 Author
+Built with ❤️ by [Ali Kahwaji].
 
-Ali Kahwaji — [@DevilsDev](https://github.com/DevilsDev)

package/USE_CASES.md

@@ -0,0 +1,134 @@
+# RAG Pipeline Utils — Developer-Focused Use Cases
+
+> Modular, composable, and CI-verified RAG orchestration for modern AI applications.
+
+---
+
+##  Use Case 1: Pluggable Local RAG Stack for Prototyping
+
+**Problem:** Traditional RAG tools force tight vendor dependencies.
+
+**Solution:** Use mockable local plugin implementations to simulate loaders, embedders, retrievers, and LLMs.
+
+```bash
+npm install @devilsdev/rag-pipeline-utils
+```
+
+```js
+// cli.js or app.js
+import { PluginRegistry } from './src/core/plugin-registry.js';
+import { loadRagConfig } from './src/config/load-config.js';
+
+const config = loadRagConfig('.ragrc.json');
+const loader = PluginRegistry.getPlugin('loader', 'pdf');
+const docs = loader.load('./test.pdf');
+```
+
+**Benefits**
+- Local plugin mocks with expected method contracts
+- Reusable plugin templates (`pdf-loader.js`, `openai-embedder.js`)
+- Dev-first DX: debug, snapshot, iterate without cloud costs
+
+---
+
+##  Use Case 2: Declarative CLI RAG Pipelines (CI-Ready)
+
+**Problem:** Hardcoded pipeline steps can't be validated or changed by non-engineers.
+
+**Solution:** Define `.ragrc.json` once and reuse across environments.
+
+```json
+{
+  "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": "docs-poc",
+  "pipeline": ["loader", "embedder", "retriever"]
+}
+```
+
+```bash
+node ./bin/cli.js ingest ./docs/whitepaper.pdf
+node ./bin/cli.js query "What’s the goal of this architecture?"
+```
+
+**Benefits**
+- Teams can standardize pipelines in source control
+- Tests fail fast if structure or mocks drift
+- Non-devs can operate pipelines via CLI
+
+---
+
+## Use Case 3: Mock-First TDD for Plugin Development
+
+**Problem:** LLM, vector, and loader logic are often developed without tests.
+
+**Solution:** Define contract-compliant mocks and CI-validate their structure before connecting to APIs.
+
+```js
+export default class CustomEmbedder {
+  embed(docs) { return docs.map(...); }
+  embedQuery(q) { return [...]; }
+}
+```
+
+Run full contract verification:
+
+```bash
+npm run ci
+```
+
+**Benefits**
+- Every plugin is CI-verified for method presence
+- Shared contracts enforce required interfaces
+- Onboarding new devs? Just follow `pluginContracts.js`
+
+---
+
+##  Use Case 4: Vendor-Neutral AI Data Pipelines
+
+**Problem:** Every RAG stack is locked to OpenAI + Pinecone + Langchain.
+
+**Solution:** Use this project to mix, match, or mock vector/LLM pairs:
+
+```js
+"retriever": { "localstore": "./src/plugins/local-retriever.js" },
+"llm": { "cohere": "./src/plugins/cohere-llm.js" }
+```
+
+**Benefits**
+- Run multiple RAG pipelines in parallel (A/B testing, evals)
+- Lower infra cost with offline/local plugin support
+- Integrate with tools outside Langchain ecosystem
+
+---
+
+## 🛠 Use Case 5: Plugin Engineering with Guardrails
+
+**Problem:** Complex plugin systems break silently.
+
+**Solution:** This framework has:
+- Plugin method contract enforcement
+- CLI test runner (`scripts/ci-runner.js`)
+- Auto repair tool (`scripts/repair-fixtures.js`)
+
+**DX Boost**
+- One-line plugin repairs
+- Validated schema structure
+- Aligned to real-world developer workflows
+
+---
+
+## Cross References
+
+- [README](./README.md) — Project overview, architecture, CLI and configuration details
+- [pluginContracts.js](./src/core/plugin-contracts.js) — Interface contracts for loader, embedder, retriever, LLM
+- [diagnostic-reporter.js](./src/utils/ci/diagnostic-reporter.js) — CI error helper
+- [repair-fixtures.js](./scripts/repair-fixtures.js) — Auto-regeneration of mocks
+
+---
+
+## License
+
+Licensed under the **GPL-3.0 License** — see [LICENSE](./LICENSE) for full terms.

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

@@ -1,7 +1,6 @@
 ---
 slug: welcome
 title: Welcome
-authors: [slorber, yangshun]
 tags: [facebook, hello, docusaurus]
 ---
 

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

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

@@ -0,0 +1,21 @@
+---
+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/authors.yml

@@ -1,23 +1,5 @@
-yangshun:
-  name: Yangshun Tay
-  title: Front End Engineer @ Facebook
-  url: https://github.com/yangshun
-  image_url: https://github.com/yangshun.png
-  page: true
-  socials:
-    x: yangshunz
-    github: yangshun
-
-slorber:
-  name: Sébastien Lorber
-  title: Docusaurus maintainer
-  url: https://sebastienlorber.com
-  image_url: https://github.com/slorber.png
-  page:
-    # customize the url of the author page at /blog/authors/<permalink>
-    permalink: '/all-sebastien-lorber-articles'
-  socials:
-    x: sebastienlorber
-    linkedin: sebastienlorber
-    github: slorber
-    newsletter: https://thisweekinreact.com
+ali:
+  name: Ali Kahwaji
+  title: Creator of RAG Pipeline Utils
+  url: https://github.com/DevilsDev
+  image_url: /img/authors/ali.jpg

package/docs-site/blog/tags.yml

@@ -17,3 +17,12 @@ hola:
   label: Hola
   permalink: /hola
   description: Hola tag description
+
+release:
+  label: Release
+  permalink: /blog/tags/release
+
+changelog:
+  label: Changelog
+  permalink: /blog/tags/changelog
+

package/docs-site/docusaurus.config.js

@@ -18,6 +18,13 @@ export default {
   // ✅ Final favicon and social card for branding
   favicon: 'img/favicon.ico',
   themeConfig: {
+    
+    // algolia: {
+    //   appId: 'YOUR_APP_ID',
+    //   apiKey: 'YOUR_PUBLIC_API_KEY',
+    //   indexName: 'rag_pipeline_utils',
+    //   contextualSearch: true,
+    // },
     image: 'img/social-card.jpg',
     navbar: {
       title: 'RAG Utils',
@@ -48,6 +55,12 @@ export default {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/'
         },
+
+        blog: {
+          showReadingTime: true,
+          editUrl: 'https://github.com/DevilsDev/rag-pipeline-utils/edit/main/docs-site/blog/',
+        },
+        
         theme: {
           customCss: require.resolve('./src/css/custom.css')
         }

package/docs-site/sidebars.js

@@ -2,21 +2,33 @@
 
 /**
  * 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', 'USE_CASES'],
+    },
+    {
+      type: 'category',
+      label: 'Developer Guide',
+      collapsed: false,
+      items: ['Usage', 'CLI', 'Plugins'],
+    },
+    {
+      type: 'category',
+      label: 'Advanced',
+      collapsed: true,
+      items: ['Evaluation', 'FAQ'],
+    },
+  ],
 };
 
 export default sidebars;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devilsdev/rag-pipeline-utils",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "A modular toolkit for building RAG (Retrieval-Augmented Generation) pipelines in Node.js",
   "main": "src/core/create-pipeline.js",
   "bin": {
@@ -17,7 +17,12 @@
     "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"
   },
   "lint-staged": {
     "**/*.{js,ts}": [
@@ -48,6 +53,8 @@
     "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",
@@ -57,6 +64,7 @@
     "@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",
     "husky": "^8.0.3",

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/docs-site/blog/2019-05-28-first-blog-post.md

@@ -1,12 +0,0 @@
----
-slug: first-blog-post
-title: First Blog Post
-authors: [slorber, yangshun]
-tags: [hola, docusaurus]
----
-
-Lorem ipsum dolor sit amet...
-
-<!-- truncate -->
-
-...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs-site/blog/2019-05-29-long-blog-post.md

@@ -1,44 +0,0 @@
----
-slug: long-blog-post
-title: Long Blog Post
-authors: yangshun
-tags: [hello, docusaurus]
----
-
-This is the summary of a very long blog post,
-
-Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
-
-<!-- truncate -->
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

package/docs-site/blog/2021-08-01-mdx-blog-post.mdx

@@ -1,24 +0,0 @@
----
-slug: mdx-blog-post
-title: MDX Blog Post
-authors: [slorber]
-tags: [docusaurus]
----
-
-Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/).
-
-:::tip
-
-Use the power of React to create interactive blog posts.
-
-:::
-
-{/* truncate */}
-
-For example, use JSX to create an interactive button:
-
-```js
-<button onClick={() => alert('button clicked!')}>Click me!</button>
-```
-
-<button onClick={() => alert('button clicked!')}>Click me!</button>