@devilsdev/rag-pipeline-utils 2.1.3 → 2.1.5

package/scripts/manual-test-checklist.md

@@ -0,0 +1,90 @@
+# ✅ 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/sync-labels.js

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

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

@@ -0,0 +1,64 @@
+/**
+ * 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!`);
+}