@imenam/mcp-documentor 1.0.99 → 1.0.101

package/scripts/migrate-links.js

@@ -1,258 +1,258 @@
-#!/usr/bin/env node
-/**
- * migrate-links.js
- *
- * Migrates inter-document references from the old slug-only format
- * to the new full-path format (folder/name) introduced in Task 10.
- *
- * Fixes two types of links:
- *   - related_docs:  ["old-slug"]         → ["folder/old-slug"]
- *   - inline links:  (doc://old-slug)      → (doc://folder/old-slug)
- *                    (doc://old-slug#h)    → (doc://folder/old-slug#h)
- *
- * Usage:
- *   node scripts/migrate-links.js [--dry-run] [--data-dir /path/to/.docs-data]
- *
- * Options:
- *   --dry-run     Show what would be changed without modifying any file.
- *   --data-dir    Override the data directory (default: <project-root>/.docs-data).
- */
-
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import matter from "gray-matter";
-
-// ---------------------------------------------------------------------------
-// Setup
-// ---------------------------------------------------------------------------
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const rootDir = path.join(__dirname, "..");
-
-const args = process.argv.slice(2);
-const dryRun = args.includes("--dry-run");
-
-const dataDirArgIdx = args.indexOf("--data-dir");
-const dataDir =
-  dataDirArgIdx !== -1 && args[dataDirArgIdx + 1]
-    ? args[dataDirArgIdx + 1]
-    : path.join(rootDir, ".docs-data");
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function walkMdFiles(dir) {
-  if (!fs.existsSync(dir)) return [];
-  const results = [];
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      results.push(...walkMdFiles(fullPath));
-    } else if (entry.isFile() && entry.name.endsWith(".md")) {
-      results.push(fullPath);
-    }
-  }
-  return results;
-}
-
-/** Derive the doc path (id) from an absolute file path within a project dir. */
-function filePathToDocId(filePath, projectDir) {
-  return path
-    .relative(projectDir, filePath)
-    .replace(/\.md$/, "")
-    .split(path.sep)
-    .join("/");
-}
-
-// ---------------------------------------------------------------------------
-// Load config
-// ---------------------------------------------------------------------------
-
-const configPath = path.join(dataDir, "config.json");
-if (!fs.existsSync(configPath)) {
-  console.error(`[ERROR] config.json not found at: ${configPath}`);
-  console.error("       Make sure --data-dir points to the right directory.");
-  process.exit(1);
-}
-
-const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-const projects = config.projects ?? ["default"];
-
-console.log(`${dryRun ? "[DRY RUN] " : ""}migrate-links`);
-console.log(`Data dir : ${dataDir}`);
-console.log(`Projects : ${projects.join(", ")}`);
-console.log("");
-
-// ---------------------------------------------------------------------------
-// Step 1 — Build the global map:  slug → [{ project, fullId }]
-//
-// A "slug" is the last segment of a doc path (the filename without .md).
-// If a slug appears in multiple projects or folders, the reference is ambiguous.
-// ---------------------------------------------------------------------------
-
-/** @type {Map<string, Array<{ project: string, fullId: string }>>} */
-const slugMap = new Map();
-
-for (const project of projects) {
-  const projectDir = path.join(dataDir, "projects", project);
-  for (const filePath of walkMdFiles(projectDir)) {
-    const fullId = filePathToDocId(filePath, projectDir);
-    const slug = fullId.split("/").pop();
-
-    if (!slugMap.has(slug)) slugMap.set(slug, []);
-    slugMap.get(slug).push({ project, fullId });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Step 2 — Scan every doc and fix links
-// ---------------------------------------------------------------------------
-
-let totalDocsChanged = 0;
-let totalLinksFixed = 0;
-let totalLinksNotFound = 0;
-let totalLinksAmbiguous = 0;
-
-/**
- * Resolve an old slug-only reference to its full path.
- * Returns { resolved: string } on success, or { error: string } otherwise.
- */
-function resolveSlug(slug) {
-  const matches = slugMap.get(slug) ?? [];
-  if (matches.length === 0) return { error: "NOT FOUND" };
-  if (matches.length > 1) {
-    return { error: `AMBIGUOUS → [${matches.map((m) => m.fullId).join(", ")}]` };
-  }
-  return { resolved: matches[0].fullId };
-}
-
-for (const project of projects) {
-  const projectDir = path.join(dataDir, "projects", project);
-  const files = walkMdFiles(projectDir);
-
-  if (files.length === 0) continue;
-
-  console.log(`\n### Project: ${project} (${files.length} docs)`);
-  console.log("");
-
-  for (const filePath of files) {
-    const fullId = filePathToDocId(filePath, projectDir);
-    const raw = fs.readFileSync(filePath, "utf-8");
-    const parsed = matter(raw);
-
-    const docChanges = [];
-    let docChanged = false;
-
-    // -----------------------------------------------------------------------
-    // Fix related_docs
-    // -----------------------------------------------------------------------
-
-    if (Array.isArray(parsed.data.related_docs)) {
-      const newRelatedDocs = [];
-
-      for (const ref of parsed.data.related_docs) {
-        // Already a full path — nothing to do
-        if (ref.includes("/")) {
-          newRelatedDocs.push(ref);
-          continue;
-        }
-
-        const result = resolveSlug(ref);
-
-        if (result.resolved) {
-          docChanges.push(`  [related_docs] "${ref}"  →  "${result.resolved}"`);
-          newRelatedDocs.push(result.resolved);
-          docChanged = true;
-          totalLinksFixed++;
-        } else {
-          docChanges.push(`  [related_docs] "${ref}"  →  ${result.error} (kept as-is)`);
-          newRelatedDocs.push(ref);
-          if (result.error === "NOT FOUND") totalLinksNotFound++;
-          else totalLinksAmbiguous++;
-        }
-      }
-
-      if (docChanged) {
-        parsed.data.related_docs = newRelatedDocs;
-      }
-    }
-
-    // -----------------------------------------------------------------------
-    // Fix inline doc:// links in content
-    //
-    // Matches: doc://slug  or  doc://slug#anchor
-    // Does NOT touch: doc://folder/slug (already full path)
-    // -----------------------------------------------------------------------
-
-    // Pattern captures:  group1 = slug-or-path,  group2 = optional #anchor
-    const docLinkRegex = /doc:\/\/([^)#\s]+)(#[^)\s]*)?/g;
-    let newContent = parsed.content;
-
-    // Collect all matches first to avoid mutation during iteration
-    const contentMatches = [];
-    let m;
-    while ((m = docLinkRegex.exec(parsed.content)) !== null) {
-      contentMatches.push({ full: m[0], ref: m[1], anchor: m[2] ?? "" });
-    }
-
-    for (const { full, ref, anchor } of contentMatches) {
-      // Already a full path
-      if (ref.includes("/")) continue;
-
-      const result = resolveSlug(ref);
-
-      if (result.resolved) {
-        const newLink = `doc://${result.resolved}${anchor}`;
-        docChanges.push(`  [doc link]    "${full}"  →  "${newLink}"`);
-        // Replace only this specific occurrence (anchor included for precision)
-        newContent = newContent.replaceAll(full, newLink);
-        docChanged = true;
-        totalLinksFixed++;
-      } else {
-        docChanges.push(`  [doc link]    "${full}"  →  ${result.error} (kept as-is)`);
-        if (result.error === "NOT FOUND") totalLinksNotFound++;
-        else totalLinksAmbiguous++;
-      }
-    }
-
-    // -----------------------------------------------------------------------
-    // Report & write
-    // -----------------------------------------------------------------------
-
-    if (docChanges.length > 0) {
-      console.log(`  [${fullId}]`);
-      docChanges.forEach((c) => console.log(c));
-      console.log("");
-    }
-
-    if (docChanged) {
-      totalDocsChanged++;
-      if (!dryRun) {
-        const output = matter.stringify(newContent, parsed.data);
-        fs.writeFileSync(filePath, output, "utf-8");
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Summary
-// ---------------------------------------------------------------------------
-
-console.log("─".repeat(60));
-console.log(`Links fixed          : ${totalLinksFixed}`);
-if (totalLinksNotFound > 0) {
-  console.log(`Links not found      : ${totalLinksNotFound}  ← target doc doesn't exist`);
-}
-if (totalLinksAmbiguous > 0) {
-  console.log(`Links ambiguous      : ${totalLinksAmbiguous}  ← same slug in multiple folders, fix manually`);
-}
-console.log(`Docs modified        : ${totalDocsChanged}`);
-
-if (dryRun) {
-  console.log("");
-  console.log("[DRY RUN] No files were modified.");
-  console.log("          Run without --dry-run to apply the changes.");
-}
+#!/usr/bin/env node
+/**
+ * migrate-links.js
+ *
+ * Migrates inter-document references from the old slug-only format
+ * to the new full-path format (folder/name) introduced in Task 10.
+ *
+ * Fixes two types of links:
+ *   - related_docs:  ["old-slug"]         → ["folder/old-slug"]
+ *   - inline links:  (doc://old-slug)      → (doc://folder/old-slug)
+ *                    (doc://old-slug#h)    → (doc://folder/old-slug#h)
+ *
+ * Usage:
+ *   node scripts/migrate-links.js [--dry-run] [--data-dir /path/to/.docs-data]
+ *
+ * Options:
+ *   --dry-run     Show what would be changed without modifying any file.
+ *   --data-dir    Override the data directory (default: <project-root>/.docs-data).
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import matter from "gray-matter";
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+
+const dataDirArgIdx = args.indexOf("--data-dir");
+const dataDir =
+  dataDirArgIdx !== -1 && args[dataDirArgIdx + 1]
+    ? args[dataDirArgIdx + 1]
+    : path.join(rootDir, ".docs-data");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function walkMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMdFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/** Derive the doc path (id) from an absolute file path within a project dir. */
+function filePathToDocId(filePath, projectDir) {
+  return path
+    .relative(projectDir, filePath)
+    .replace(/\.md$/, "")
+    .split(path.sep)
+    .join("/");
+}
+
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+
+const configPath = path.join(dataDir, "config.json");
+if (!fs.existsSync(configPath)) {
+  console.error(`[ERROR] config.json not found at: ${configPath}`);
+  console.error("       Make sure --data-dir points to the right directory.");
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const projects = config.projects ?? ["default"];
+
+console.log(`${dryRun ? "[DRY RUN] " : ""}migrate-links`);
+console.log(`Data dir : ${dataDir}`);
+console.log(`Projects : ${projects.join(", ")}`);
+console.log("");
+
+// ---------------------------------------------------------------------------
+// Step 1 — Build the global map:  slug → [{ project, fullId }]
+//
+// A "slug" is the last segment of a doc path (the filename without .md).
+// If a slug appears in multiple projects or folders, the reference is ambiguous.
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, Array<{ project: string, fullId: string }>>} */
+const slugMap = new Map();
+
+for (const project of projects) {
+  const projectDir = path.join(dataDir, "projects", project);
+  for (const filePath of walkMdFiles(projectDir)) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const slug = fullId.split("/").pop();
+
+    if (!slugMap.has(slug)) slugMap.set(slug, []);
+    slugMap.get(slug).push({ project, fullId });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step 2 — Scan every doc and fix links
+// ---------------------------------------------------------------------------
+
+let totalDocsChanged = 0;
+let totalLinksFixed = 0;
+let totalLinksNotFound = 0;
+let totalLinksAmbiguous = 0;
+
+/**
+ * Resolve an old slug-only reference to its full path.
+ * Returns { resolved: string } on success, or { error: string } otherwise.
+ */
+function resolveSlug(slug) {
+  const matches = slugMap.get(slug) ?? [];
+  if (matches.length === 0) return { error: "NOT FOUND" };
+  if (matches.length > 1) {
+    return { error: `AMBIGUOUS → [${matches.map((m) => m.fullId).join(", ")}]` };
+  }
+  return { resolved: matches[0].fullId };
+}
+
+for (const project of projects) {
+  const projectDir = path.join(dataDir, "projects", project);
+  const files = walkMdFiles(projectDir);
+
+  if (files.length === 0) continue;
+
+  console.log(`\n### Project: ${project} (${files.length} docs)`);
+  console.log("");
+
+  for (const filePath of files) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = matter(raw);
+
+    const docChanges = [];
+    let docChanged = false;
+
+    // -----------------------------------------------------------------------
+    // Fix related_docs
+    // -----------------------------------------------------------------------
+
+    if (Array.isArray(parsed.data.related_docs)) {
+      const newRelatedDocs = [];
+
+      for (const ref of parsed.data.related_docs) {
+        // Already a full path — nothing to do
+        if (ref.includes("/")) {
+          newRelatedDocs.push(ref);
+          continue;
+        }
+
+        const result = resolveSlug(ref);
+
+        if (result.resolved) {
+          docChanges.push(`  [related_docs] "${ref}"  →  "${result.resolved}"`);
+          newRelatedDocs.push(result.resolved);
+          docChanged = true;
+          totalLinksFixed++;
+        } else {
+          docChanges.push(`  [related_docs] "${ref}"  →  ${result.error} (kept as-is)`);
+          newRelatedDocs.push(ref);
+          if (result.error === "NOT FOUND") totalLinksNotFound++;
+          else totalLinksAmbiguous++;
+        }
+      }
+
+      if (docChanged) {
+        parsed.data.related_docs = newRelatedDocs;
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Fix inline doc:// links in content
+    //
+    // Matches: doc://slug  or  doc://slug#anchor
+    // Does NOT touch: doc://folder/slug (already full path)
+    // -----------------------------------------------------------------------
+
+    // Pattern captures:  group1 = slug-or-path,  group2 = optional #anchor
+    const docLinkRegex = /doc:\/\/([^)#\s]+)(#[^)\s]*)?/g;
+    let newContent = parsed.content;
+
+    // Collect all matches first to avoid mutation during iteration
+    const contentMatches = [];
+    let m;
+    while ((m = docLinkRegex.exec(parsed.content)) !== null) {
+      contentMatches.push({ full: m[0], ref: m[1], anchor: m[2] ?? "" });
+    }
+
+    for (const { full, ref, anchor } of contentMatches) {
+      // Already a full path
+      if (ref.includes("/")) continue;
+
+      const result = resolveSlug(ref);
+
+      if (result.resolved) {
+        const newLink = `doc://${result.resolved}${anchor}`;
+        docChanges.push(`  [doc link]    "${full}"  →  "${newLink}"`);
+        // Replace only this specific occurrence (anchor included for precision)
+        newContent = newContent.replaceAll(full, newLink);
+        docChanged = true;
+        totalLinksFixed++;
+      } else {
+        docChanges.push(`  [doc link]    "${full}"  →  ${result.error} (kept as-is)`);
+        if (result.error === "NOT FOUND") totalLinksNotFound++;
+        else totalLinksAmbiguous++;
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Report & write
+    // -----------------------------------------------------------------------
+
+    if (docChanges.length > 0) {
+      console.log(`  [${fullId}]`);
+      docChanges.forEach((c) => console.log(c));
+      console.log("");
+    }
+
+    if (docChanged) {
+      totalDocsChanged++;
+      if (!dryRun) {
+        const output = matter.stringify(newContent, parsed.data);
+        fs.writeFileSync(filePath, output, "utf-8");
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log("─".repeat(60));
+console.log(`Links fixed          : ${totalLinksFixed}`);
+if (totalLinksNotFound > 0) {
+  console.log(`Links not found      : ${totalLinksNotFound}  ← target doc doesn't exist`);
+}
+if (totalLinksAmbiguous > 0) {
+  console.log(`Links ambiguous      : ${totalLinksAmbiguous}  ← same slug in multiple folders, fix manually`);
+}
+console.log(`Docs modified        : ${totalDocsChanged}`);
+
+if (dryRun) {
+  console.log("");
+  console.log("[DRY RUN] No files were modified.");
+  console.log("          Run without --dry-run to apply the changes.");
+}