@chappibunny/repolens 0.4.1

package/src/migrate.js

@@ -0,0 +1,251 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info, warn, error as logError } from "./utils/logger.js";
+
+/**
+ * Detect legacy workflow patterns that need migration
+ */
+function detectLegacyPatterns(content) {
+  const patterns = {
+    cdToolsRepolens: /cd\s+tools\/repolens/i.test(content),
+    npmInstallRepolens: /npm\s+(?:ci|install)(?:\s|$)(?!.*repolens@)/m.test(content),
+    npxWithoutLatest: /npx\s+repolens\s+(?!@latest)/m.test(content),
+    missingNodeSetup: !content.includes("actions/setup-node@"),
+    missingEnvVars: !content.includes("NOTION_TOKEN") && !content.includes("env:")
+  };
+
+  const detected = [];
+  if (patterns.cdToolsRepolens) {
+    detected.push("cd tools/repolens");
+  }
+  if (patterns.npmInstallRepolens) {
+    detected.push("npm install without @latest");
+  }
+  if (patterns.npxWithoutLatest) {
+    detected.push("npx repolens without @latest");
+  }
+  if (patterns.missingNodeSetup) {
+    detected.push("missing Node.js setup");
+  }
+  if (patterns.missingEnvVars) {
+    detected.push("missing environment variables");
+  }
+
+  return {
+    isLegacy: detected.length > 0,
+    patterns: detected
+  };
+}
+
+/**
+ * Migrate workflow to v0.4.0 format
+ */
+function migrateWorkflowContent(content) {
+  let migrated = content;
+
+  // Remove cd tools/repolens commands
+  migrated = migrated.replace(/cd\s+tools\/repolens\s*\n?/gi, "");
+  
+  // Remove standalone npm ci/install that's part of old setup
+  migrated = migrated.replace(/npm\s+(?:ci|install)\s*\n/g, "");
+
+  // Update npx repolens to npx repolens@latest
+  migrated = migrated.replace(/npx\s+repolens\s+/g, "npx repolens@latest ");
+
+  // Add Node.js setup if missing (insert after checkout step)
+  if (!migrated.includes("actions/setup-node@")) {
+    const checkoutPattern = /(- name: Checkout repository\s+uses: actions\/checkout@v\d+)/;
+    if (checkoutPattern.test(migrated)) {
+      migrated = migrated.replace(
+        checkoutPattern,
+        `$1
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20`
+      );
+    }
+  }
+
+  // Add environment variables if missing
+  if (!migrated.includes("NOTION_TOKEN") && !migrated.includes("env:")) {
+    // Find the publish/generate documentation step
+    const publishPattern = /(- name: .*(?:publish|generate).*documentation.*\n)/i;
+    if (publishPattern.test(migrated)) {
+      migrated = migrated.replace(
+        publishPattern,
+        `$1        env:
+          NOTION_TOKEN: \${{ secrets.NOTION_TOKEN }}
+          NOTION_PARENT_PAGE_ID: \${{ secrets.NOTION_PARENT_PAGE_ID }}
+          REPOLENS_AI_API_KEY: \${{ secrets.REPOLENS_AI_API_KEY }}
+          REPOLENS_AI_PROVIDER: openai
+        `
+      );
+    }
+  }
+
+  // Add AI environment variables if env section exists but missing AI vars
+  if (migrated.includes("NOTION_TOKEN") && !migrated.includes("REPOLENS_AI_API_KEY")) {
+    migrated = migrated.replace(
+      /(NOTION_PARENT_PAGE_ID: \${{ secrets\.NOTION_PARENT_PAGE_ID }})/,
+      `$1
+          REPOLENS_AI_API_KEY: \${{ secrets.REPOLENS_AI_API_KEY }}
+          REPOLENS_AI_PROVIDER: openai`
+    );
+  }
+
+  return migrated;
+}
+
+/**
+ * Find all workflow files in .github/workflows
+ */
+async function findWorkflowFiles(targetDir) {
+  const workflowDir = path.join(targetDir, ".github", "workflows");
+  
+  try {
+    await fs.access(workflowDir);
+  } catch {
+    return [];
+  }
+
+  const files = await fs.readdir(workflowDir);
+  const workflowFiles = files.filter(f => f.endsWith(".yml") || f.endsWith(".yaml"));
+  
+  return workflowFiles.map(f => path.join(workflowDir, f));
+}
+
+/**
+ * Show diff between old and new content
+ */
+function showDiff(oldContent, newContent) {
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  const maxLines = Math.max(oldLines.length, newLines.length);
+
+  console.log("\n📋 Changes Preview:");
+  console.log("─".repeat(60));
+
+  let changesShown = 0;
+  for (let i = 0; i < maxLines; i++) {
+    const oldLine = oldLines[i] || "";
+    const newLine = newLines[i] || "";
+
+    if (oldLine !== newLine) {
+      if (oldLine) {
+        console.log(`  - ${oldLine}`);
+      }
+      if (newLine) {
+        console.log(`  + ${newLine}`);
+      }
+      changesShown++;
+      if (changesShown > 20) {
+        console.log(`  ... (${maxLines - i} more lines)`);
+        break;
+      }
+    }
+  }
+
+  console.log("─".repeat(60));
+}
+
+/**
+ * Main migration function
+ */
+export async function runMigrate(targetDir = process.cwd(), options = {}) {
+  const { dryRun = false, force = false } = options;
+
+  try {
+    await printMigrationBanner();
+
+    info(`🔍 Scanning for workflow files in: ${targetDir}`);
+    
+    const workflowFiles = await findWorkflowFiles(targetDir);
+
+    if (workflowFiles.length === 0) {
+      warn("⚠️  No workflow files found in .github/workflows/");
+      info("\n💡 If you haven't set up GitHub Actions yet:");
+      info("   Run: repolens init");
+      return;
+    }
+
+    info(`   Found ${workflowFiles.length} workflow file(s)`);
+
+    let migratedCount = 0;
+    let skippedCount = 0;
+
+    for (const workflowPath of workflowFiles) {
+      const filename = path.basename(workflowPath);
+      console.log(`\n📄 Checking: ${filename}`);
+
+      const content = await fs.readFile(workflowPath, "utf8");
+      const detection = detectLegacyPatterns(content);
+
+      if (!detection.isLegacy) {
+        info("   ✅ Already up to date!");
+        skippedCount++;
+        continue;
+      }
+
+      info("   🔧 Legacy patterns detected:");
+      detection.patterns.forEach(p => info(`      - ${p}`));
+
+      const migratedContent = migrateWorkflowContent(content);
+
+      if (!force) {
+        showDiff(content, migratedContent);
+      }
+
+      if (dryRun) {
+        info("\n   🔍 DRY RUN: No changes written");
+        migratedCount++;
+        continue;
+      }
+
+      // Backup original file
+      const backupPath = `${workflowPath}.backup`;
+      await fs.writeFile(backupPath, content, "utf8");
+      info(`   💾 Backup saved: ${path.basename(backupPath)}`);
+
+      // Write migrated content
+      await fs.writeFile(workflowPath, migratedContent, "utf8");
+      info(`   ✅ Migrated: ${filename}`);
+      migratedCount++;
+    }
+
+    // Summary
+    console.log("\n" + "─".repeat(60));
+    console.log("📊 Migration Summary:");
+    console.log(`   ✅ Migrated: ${migratedCount}`);
+    console.log(`   ⏭️  Skipped: ${skippedCount}`);
+    
+    if (migratedCount > 0) {
+      console.log("\n🎉 Migration complete!");
+      
+      if (!dryRun) {
+        console.log("\n📝 Next steps:");
+        console.log("   1. Review the changes: git diff .github/workflows/");
+        console.log("   2. Test locally: npx repolens@latest publish");
+        console.log("   3. Commit: git add .github/workflows/ && git commit -m 'chore: migrate RepoLens workflow to v0.4.0'");
+        console.log("   4. Push: git push");
+        console.log("\n💡 Tip: Backups saved as *.backup - delete them once verified");
+      } else {
+        console.log("\n💡 Run without --dry-run to apply changes");
+      }
+    } else {
+      console.log("\n✨ All workflows are up to date!");
+    }
+
+  } catch (err) {
+    logError(`Migration failed: ${err.message}`);
+    throw err;
+  }
+}
+
+async function printMigrationBanner() {
+  console.log("\n" + "=".repeat(60));
+  console.log("🔄 RepoLens Workflow Migration Tool");
+  console.log("   Upgrading to v0.4.0 format");
+  console.log("=".repeat(60));
+}

package/src/publishers/index.js

@@ -0,0 +1,33 @@
+import { publishToNotion } from "./publish.js";
+import { publishToMarkdown } from "./markdown.js";
+import { shouldPublishToNotion, getCurrentBranch } from "../utils/branch.js";
+import { info, warn } from "../utils/logger.js";
+
+function hasNotionSecrets() {
+  return !!process.env.NOTION_TOKEN && !!process.env.NOTION_PARENT_PAGE_ID;
+}
+
+export async function publishDocs(cfg, renderedPages) {
+  const publishers = cfg.publishers || ["markdown", "notion"];
+  const currentBranch = getCurrentBranch();
+
+  // Always try Notion publishing if secrets are configured
+  if (publishers.includes("notion") || hasNotionSecrets()) {
+    if (!hasNotionSecrets()) {
+      info("Skipping Notion publish: NOTION_TOKEN or NOTION_PARENT_PAGE_ID not configured");
+      info("To enable Notion publishing, set these environment variables or GitHub Actions secrets");
+    } else if (shouldPublishToNotion(cfg, currentBranch)) {
+      info(`Publishing to Notion from branch: ${currentBranch}`);
+      await publishToNotion(cfg, renderedPages);
+    } else {
+      const allowedBranches = cfg.notion?.branches?.join(", ") || "none configured";
+      warn(`Skipping Notion publish: branch "${currentBranch}" not in allowed list (${allowedBranches})`);
+      info("To publish from this branch, add it to notion.branches in .repolens.yml");
+    }
+  }
+
+  // Always generate markdown output
+  if (publishers.includes("markdown") || !publishers.includes("notion")) {
+    await publishToMarkdown(cfg, renderedPages);
+  }
+}

package/src/publishers/markdown.js

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { info } from "../utils/logger.js";
+
+function outputDir(cfg) {
+  return path.join(cfg.__repoRoot, ".repolens");
+}
+
+function pageFileName(key) {
+  const mapping = {
+    system_overview: "system_overview.md",
+    module_catalog: "module_catalog.md",
+    api_surface: "api_surface.md",
+    arch_diff: "architecture_diff.md",
+    route_map: "route_map.md",
+    system_map: "system_map.md"
+  };
+
+  return mapping[key] || `${key}.md`;
+}
+
+export async function publishToMarkdown(cfg, renderedPages) {
+  const dir = outputDir(cfg);
+  await fs.mkdir(dir, { recursive: true });
+
+  for (const [key, markdown] of Object.entries(renderedPages)) {
+    const filePath = path.join(dir, pageFileName(key));
+    await fs.writeFile(filePath, markdown, "utf8");
+  }
+
+  info(`markdown docs written to ${dir}`);
+}

package/src/publishers/notion.js

@@ -0,0 +1,325 @@
+import fetch from "node-fetch";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { log } from "../utils/logger.js";
+import { fetchWithRetry } from "../utils/retry.js";
+
+function notionHeaders() {
+  const token = process.env.NOTION_TOKEN;
+  const version = process.env.NOTION_VERSION || "2022-06-28";
+
+  if (!token) {
+    throw new Error("Missing NOTION_TOKEN in tools/repolens/.env or GitHub Actions secrets");
+  }
+
+  return {
+    Authorization: `Bearer ${token}`,
+    "Notion-Version": version,
+    "Content-Type": "application/json"
+  };
+}
+
+async function notionRequest(method, url, body) {
+  const res = await fetchWithRetry(`https://api.notion.com/v1${url}`, {
+    method,
+    headers: notionHeaders(),
+    body: body ? JSON.stringify(body) : undefined
+  }, {
+    retries: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 4000,
+    label: `Notion ${method} ${url}`
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Notion API error ${res.status}: ${text}`);
+  }
+
+  return await res.json();
+}
+
+const CACHE_DIR = path.join(process.cwd(), ".cache");
+const CACHE_FILE = path.join(CACHE_DIR, "notion-pages.json");
+
+async function readCache() {
+  try {
+    const raw = await fs.readFile(CACHE_FILE, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+async function writeCache(cache) {
+  await fs.mkdir(CACHE_DIR, { recursive: true });
+  await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf8");
+}
+
+async function getChildBlocks(blockId) {
+  const results = [];
+  let cursor = undefined;
+
+  while (true) {
+    const suffix = cursor ? `?start_cursor=${cursor}` : "";
+    const response = await notionRequest("GET", `/blocks/${blockId}/children${suffix}`);
+
+    if (response.results?.length) {
+      results.push(...response.results);
+    }
+
+    if (!response.has_more || !response.next_cursor) {
+      break;
+    }
+
+    cursor = response.next_cursor;
+  }
+
+  return results;
+}
+
+async function findExistingChildPageByTitle(parentPageId, title) {
+  const children = await getChildBlocks(parentPageId);
+
+  log(`Looking for child page: "${title}"`);
+  log(`Parent has ${children.length} child blocks`);
+
+  for (const child of children) {
+    if (child.type === "child_page") {
+      const childTitle = child.child_page?.title?.trim();
+      log(`Found child page block: "${childTitle}" (${child.id})`);
+
+      if (childTitle === title) {
+        log(`Reusing existing page: "${title}" (${child.id})`);
+        return child.id;
+      }
+    }
+  }
+
+  log(`No existing child page found for "${title}"`);
+  return null;
+}
+
+export async function ensurePage(parentPageId, title, cacheKey) {
+  const cache = await readCache();
+
+  if (cache[cacheKey]) {
+    log(`Using cached page ID for ${cacheKey}: ${cache[cacheKey]}`);
+    return cache[cacheKey];
+  }
+
+  const existingId = await findExistingChildPageByTitle(parentPageId, title);
+
+  if (existingId) {
+    cache[cacheKey] = existingId;
+    await writeCache(cache);
+    return existingId;
+  }
+
+  log(`Creating NEW page for "${title}"`);
+
+  const created = await notionRequest("POST", "/pages", {
+    parent: { page_id: parentPageId },
+    properties: {
+      title: {
+        title: [
+          {
+            text: {
+              content: title
+            }
+          }
+        ]
+      }
+    }
+  });
+
+  cache[cacheKey] = created.id;
+  await writeCache(cache);
+
+  log(`Created page "${title}" with ID ${created.id}`);
+  return created.id;
+}
+
+async function archiveBlock(blockId) {
+  return notionRequest("PATCH", `/blocks/${blockId}`, {
+    archived: true
+  });
+}
+
+async function unarchivePage(pageId) {
+  try {
+    return await notionRequest("PATCH", `/pages/${pageId}`, {
+      archived: false
+    });
+  } catch (error) {
+    // If page is already unarchived, ignore error
+    log(`Note: Could not unarchive page ${pageId}: ${error.message}`);
+  }
+}
+
+export async function clearPage(pageId) {
+  const children = await getChildBlocks(pageId);
+
+  // Only archive blocks that are not already archived
+  const unarchivedBlocks = children.filter(child => !child.archived);
+  
+  for (const child of unarchivedBlocks) {
+    await archiveBlock(child.id);
+  }
+}
+
+function markdownToNotionBlocks(markdown) {
+  // Safety check: handle undefined/null markdown
+  if (!markdown || typeof markdown !== 'string') {
+    console.warn(`Warning: markdownToNotionBlocks received invalid markdown: ${typeof markdown}`);
+    return [];
+  }
+  
+  const lines = markdown.split("\n");
+  const blocks = [];
+  let i = 0;
+
+  while (i < lines.length && blocks.length < 100) {
+    const line = lines[i].trim();
+
+    // Skip empty lines
+    if (!line) {
+      i++;
+      continue;
+    }
+
+    // Handle code blocks (```language...```)
+    if (line.startsWith("```")) {
+      const language = line.slice(3).trim() || "plain text";
+      const codeLines = [];
+      i++; // Move past opening ```
+
+      // Collect code block content
+      while (i < lines.length && !lines[i].trim().startsWith("```")) {
+        codeLines.push(lines[i]);
+        i++;
+      }
+
+      // Create Notion code block
+      const codeContent = codeLines.join("\n");
+      if (codeContent.trim()) {
+        blocks.push({
+          object: "block",
+          type: "code",
+          code: {
+            rich_text: [
+              {
+                type: "text",
+                text: {
+                  content: codeContent.slice(0, 2000) // Notion limit
+                }
+              }
+            ],
+            language: language,
+            caption: []
+          }
+        });
+      }
+
+      i++; // Move past closing ```
+      continue;
+    }
+
+    // Handle headings
+    if (line.startsWith("# ")) {
+      blocks.push({
+        object: "block",
+        type: "heading_1",
+        heading_1: {
+          rich_text: [
+            {
+              type: "text",
+              text: {
+                content: line.replace(/^# /, "")
+              }
+            }
+          ]
+        }
+      });
+      i++;
+      continue;
+    }
+
+    if (line.startsWith("## ")) {
+      blocks.push({
+        object: "block",
+        type: "heading_2",
+        heading_2: {
+          rich_text: [
+            {
+              type: "text",
+              text: {
+                content: line.replace(/^## /, "")
+              }
+            }
+          ]
+        }
+      });
+      i++;
+      continue;
+    }
+
+    // Handle bullet lists
+    if (line.startsWith("- ")) {
+      blocks.push({
+        object: "block",
+        type: "bulleted_list_item",
+        bulleted_list_item: {
+          rich_text: [
+            {
+              type: "text",
+              text: {
+                content: line.replace(/^- /, "")
+              }
+            }
+          ]
+        }
+      });
+      i++;
+      continue;
+    }
+
+    // Handle regular paragraphs
+    blocks.push({
+      object: "block",
+      type: "paragraph",
+      paragraph: {
+        rich_text: [
+          {
+            type: "text",
+            text: {
+              content: line
+            }
+          }
+        ]
+      }
+    });
+    i++;
+  }
+
+  return blocks;
+}
+
+export async function replacePageContent(pageId, markdown) {
+  // Ensure page is unarchived before editing
+  await unarchivePage(pageId);
+  
+  await clearPage(pageId);
+
+  const children = markdownToNotionBlocks(markdown);
+
+  if (!children.length) return;
+
+  for (let i = 0; i < children.length; i += 50) {
+    const chunk = children.slice(i, i + 50);
+
+    await notionRequest("PATCH", `/blocks/${pageId}/children`, {
+      children: chunk
+    });
+  }
+}

package/src/publishers/publish.js

@@ -0,0 +1,31 @@
+import { ensurePage, replacePageContent } from "./notion.js";
+import { getCurrentBranch, getBranchQualifiedTitle } from "../utils/branch.js";
+
+export async function publishToNotion(cfg, renderedPages) {
+  const parentPageId = process.env.NOTION_PARENT_PAGE_ID;
+
+  if (!parentPageId) {
+    throw new Error("Missing NOTION_PARENT_PAGE_ID in tools/repolens/.env");
+  }
+
+  const prefix = cfg.project.docs_title_prefix || "RepoLens";
+  const currentBranch = getCurrentBranch();
+  const includeBranchInTitle = cfg.notion?.includeBranchInTitle !== false; // Default true
+
+  for (const page of cfg.outputs.pages) {
+    const baseTitle = `${prefix} — ${page.title}`;
+    const title = getBranchQualifiedTitle(baseTitle, currentBranch, includeBranchInTitle);
+    const cacheKey = `${page.key}-${currentBranch}`; // Branch-scoped cache
+    
+    const pageId = await ensurePage(parentPageId, title, cacheKey);
+    const markdown = renderedPages[page.key];
+    
+    // Skip if content not generated (e.g., disabled feature or generation error)
+    if (!markdown) {
+      console.log(`⚠️  Skipping ${page.key}: No content generated`);
+      continue;
+    }
+    
+    await replacePageContent(pageId, markdown);
+  }
+}