@mui/internal-docs-infra 0.3.1-canary.3 → 0.3.1-canary.4

package/esm/pipeline/syncPageIndex/syncPageIndex.js

@@ -1,8 +1,3 @@
-import _regeneratorValues from "@babel/runtime/helpers/esm/regeneratorValues";
-import _regenerator from "@babel/runtime/helpers/esm/regenerator";
-import _extends from "@babel/runtime/helpers/esm/extends";
-import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
-import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { basename, dirname, resolve, relative, join } from 'node:path';
 import * as lockfile from 'proper-lockfile';
@@ -14,9 +9,7 @@ import { markdownToMetadata } from "./metadataToMarkdown.js";
  * @example kebabToTitleCase('hello-world') -> 'Hello World'
  */
 function kebabToTitleCase(str) {
-  return str.split('-').map(function (word) {
-    return word.charAt(0).toUpperCase() + word.slice(1);
-  }).join(' ');
+  return str.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
 }
 
 /**
@@ -33,9 +26,8 @@ function isRouteGroup(dirName) {
  * @example getParentDir('/app/(public)/(content)/react') -> '/app/(public)/(content)'
  * When recursing, skips route groups: '/app/(public)/(content)' -> '/app'
  */
-function getParentDir(path) {
-  var skipRouteGroups = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
-  var parent = dirname(path);
+function getParentDir(path, skipRouteGroups = false) {
+  let parent = dirname(path);
 
   // If we should skip route groups, keep going up until we find a non-route-group directory
   if (skipRouteGroups) {
@@ -55,24 +47,15 @@ function getParentDir(path) {
  */
 function shouldIncludePath(path, include, exclude) {
   // Normalize path separators to forward slashes and remove Next.js route groups
-  var normalizedPath = path.replace(/\\/g, '/').replace(/\/\([^)]+\)/g, '');
+  const normalizedPath = path.replace(/\\/g, '/').replace(/\/\([^)]+\)/g, '');
 
   // Check exclude patterns first
   if (exclude && exclude.length > 0) {
-    var _iterator = _createForOfIteratorHelper(exclude),
-      _step;
-    try {
-      for (_iterator.s(); !(_step = _iterator.n()).done;) {
-        var pattern = _step.value;
-        var normalizedPattern = pattern.replace(/\\/g, '/');
-        if (normalizedPath.startsWith(normalizedPattern)) {
-          return false;
-        }
+    for (const pattern of exclude) {
+      const normalizedPattern = pattern.replace(/\\/g, '/');
+      if (normalizedPath.startsWith(normalizedPattern)) {
+        return false;
       }
-    } catch (err) {
-      _iterator.e(err);
-    } finally {
-      _iterator.f();
     }
   }
 
@@ -82,23 +65,14 @@ function shouldIncludePath(path, include, exclude) {
   }
 
   // Check if path matches any include pattern
-  var _iterator2 = _createForOfIteratorHelper(include),
-    _step2;
-  try {
-    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
-      var _pattern = _step2.value;
-      var _normalizedPattern = _pattern.replace(/\\/g, '/');
-      if (normalizedPath.startsWith(_normalizedPattern)) {
-        return true;
-      }
+  for (const pattern of include) {
+    const normalizedPattern = pattern.replace(/\\/g, '/');
+    if (normalizedPath.startsWith(normalizedPattern)) {
+      return true;
     }
-
-    // Path doesn't match any include pattern
-  } catch (err) {
-    _iterator2.e(err);
-  } finally {
-    _iterator2.f();
   }
+
+  // Path doesn't match any include pattern
   return false;
 }
 /**
@@ -126,369 +100,265 @@ function shouldIncludePath(path, include, exclude) {
  * });
  * ```
  */
-export function syncPageIndex(_x) {
-  return _syncPageIndex.apply(this, arguments);
-}
-function _syncPageIndex() {
-  _syncPageIndex = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(options) {
-    var _options$indexTitle;
-    var pagePath, metadata, metadataList, _options$indexFileNam, indexFileName, _options$lockOptions, lockOptions, baseDir, _options$updateParent, updateParents, include, exclude, _options$onlyUpdateIn, onlyUpdateIndexes, _options$markerDir, markerDir, _options$errorIfOutOf, errorIfOutOfDate, indexWrapperComponent, isBatchUpdate, metadataArray, indexPath, parentDir, relativePath, shouldStop, indexTitle, existingContent, fileExists, relativeIndexPath, hasMarker, existingMarkdown, existingPages, parsed, needsUpdate, _iterator3, _step3, _loop, _ret, _relativeIndexPath, release, mergedPages, currentContent, currentMarkdown, currentPages, _parsed, updatedPagesMap, _iterator4, _step4, page, _iterator5, _step5, metaItem, allPages, _relativeIndexPath2, finalMarkdown, markerRelativePath, markerDirResolved, markerPath, markerDirPath, grandParentDir, relativePathFromGrandparent, indexMetadata, sections, _iterator6, _step6, childPage, _t, _t2, _t3, _t4;
-    return _regenerator().w(function (_context2) {
-      while (1) switch (_context2.p = _context2.n) {
-        case 0:
-          pagePath = options.pagePath, metadata = options.metadata, metadataList = options.metadataList, _options$indexFileNam = options.indexFileName, indexFileName = _options$indexFileNam === void 0 ? 'page.mdx' : _options$indexFileNam, _options$lockOptions = options.lockOptions, lockOptions = _options$lockOptions === void 0 ? {} : _options$lockOptions, baseDir = options.baseDir, _options$updateParent = options.updateParents, updateParents = _options$updateParent === void 0 ? false : _options$updateParent, include = options.include, exclude = options.exclude, _options$onlyUpdateIn = options.onlyUpdateIndexes, onlyUpdateIndexes = _options$onlyUpdateIn === void 0 ? false : _options$onlyUpdateIn, _options$markerDir = options.markerDir, markerDir = _options$markerDir === void 0 ? false : _options$markerDir, _options$errorIfOutOf = options.errorIfOutOfDate, errorIfOutOfDate = _options$errorIfOutOf === void 0 ? false : _options$errorIfOutOf, indexWrapperComponent = options.indexWrapperComponent; // Validate that either metadata or metadataList is provided
-          if (!(!metadata && (!metadataList || metadataList.length === 0))) {
-            _context2.n = 1;
-            break;
-          }
-          throw new Error('Either metadata or metadataList must be provided');
-        case 1:
-          // Determine if we're doing a batch update
-          isBatchUpdate = !!metadataList;
-          metadataArray = isBatchUpdate ? metadataList : [metadata]; // Resolve the index file path
-          // For batch updates, pagePath is the index file itself
-          // For single updates, pagePath is a child page and we need the parent's index
-          indexPath = isBatchUpdate ? resolve(pagePath) : resolve(getParentDir(dirname(pagePath), true), indexFileName);
-          parentDir = dirname(indexPath); // Check if this index path should be processed based on include/exclude filters
-          if (!baseDir) {
-            _context2.n = 2;
-            break;
-          }
-          relativePath = relative(resolve(baseDir), resolve(parentDir));
-          if (shouldIncludePath(relativePath, include, exclude)) {
-            _context2.n = 2;
-            break;
-          }
-          return _context2.a(2);
-        case 2:
-          // Check if we've reached the base directory
-          shouldStop = baseDir && resolve(parentDir) === resolve(baseDir); // Derive index title from directory name if not provided
-          indexTitle = (_options$indexTitle = options.indexTitle) != null ? _options$indexTitle : kebabToTitleCase(basename(parentDir)); // Step 1: Read the file without acquiring a lock to check if we need to make changes
-          existingContent = '';
-          fileExists = true;
-          _context2.p = 3;
-          _context2.n = 4;
-          return readFile(indexPath, 'utf-8');
-        case 4:
-          existingContent = _context2.v;
-          _context2.n = 8;
-          break;
-        case 5:
-          _context2.p = 5;
-          _t = _context2.v;
-          if (!(_t.code !== 'ENOENT')) {
-            _context2.n = 6;
-            break;
-          }
-          throw _t;
-        case 6:
-          // File doesn't exist
-          fileExists = false;
-
-          // If onlyUpdateIndexes is true and file doesn't exist, skip this update
-          if (!onlyUpdateIndexes) {
-            _context2.n = 7;
-            break;
-          }
-          return _context2.a(2);
-        case 7:
-          if (!errorIfOutOfDate) {
-            _context2.n = 8;
-            break;
-          }
-          relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
-          throw new Error("Index file is missing: ".concat(relativeIndexPath, "\n") + "Please run next build locally and commit the updated index files.\n" + "Don't forget to add it to the `app/sitemap/index.ts` to list it publicly.");
-        case 8:
-          if (!(fileExists && existingContent)) {
-            _context2.n = 9;
-            break;
-          }
-          hasMarker = existingContent.includes("[//]: # 'This file is autogenerated");
-          if (hasMarker) {
-            _context2.n = 9;
-            break;
-          }
-          return _context2.a(2);
-        case 9:
-          // Step 2: Parse existing content and check if our specific page needs updating
-          existingMarkdown = existingContent.trim() ? existingContent : undefined;
-          existingPages = [];
-          if (!existingMarkdown) {
-            _context2.n = 11;
-            break;
-          }
-          _context2.n = 10;
-          return markdownToMetadata(existingMarkdown);
-        case 10:
-          parsed = _context2.v;
-          if (parsed) {
-            existingPages = parsed.pages;
-          }
-        case 11:
-          // Step 3: Check if any of our metadata items need updating
-          needsUpdate = false;
-          _iterator3 = _createForOfIteratorHelper(metadataArray);
-          _context2.p = 12;
-          _loop = /*#__PURE__*/_regenerator().m(function _loop() {
-            var metaItem, existingPageIndex, existingPage, existingPageJson, newPageJson;
-            return _regenerator().w(function (_context) {
-              while (1) switch (_context.n) {
-                case 0:
-                  metaItem = _step3.value;
-                  existingPageIndex = existingPages.findIndex(function (p) {
-                    return p.slug === metaItem.slug;
-                  });
-                  if (!(existingPageIndex >= 0)) {
-                    _context.n = 2;
-                    break;
-                  }
-                  existingPage = existingPages[existingPageIndex]; // Compare metadata - if different, we need to update
-                  existingPageJson = JSON.stringify(existingPage);
-                  newPageJson = JSON.stringify(metaItem);
-                  if (!(existingPageJson !== newPageJson)) {
-                    _context.n = 1;
-                    break;
-                  }
-                  needsUpdate = true;
-                  return _context.a(2, 0);
-                case 1:
-                  _context.n = 3;
-                  break;
-                case 2:
-                  // Page doesn't exist, we need to add it
-                  needsUpdate = true;
-                  return _context.a(2, 0);
-                case 3:
-                  return _context.a(2);
-              }
-            }, _loop);
-          });
-          _iterator3.s();
-        case 13:
-          if ((_step3 = _iterator3.n()).done) {
-            _context2.n = 16;
-            break;
-          }
-          return _context2.d(_regeneratorValues(_loop()), 14);
-        case 14:
-          _ret = _context2.v;
-          if (!(_ret === 0)) {
-            _context2.n = 15;
-            break;
-          }
-          return _context2.a(3, 16);
-        case 15:
-          _context2.n = 13;
-          break;
-        case 16:
-          _context2.n = 18;
-          break;
-        case 17:
-          _context2.p = 17;
-          _t2 = _context2.v;
-          _iterator3.e(_t2);
-        case 18:
-          _context2.p = 18;
-          _iterator3.f();
-          return _context2.f(18);
-        case 19:
-          if (needsUpdate) {
-            _context2.n = 20;
-            break;
-          }
-          return _context2.a(2);
-        case 20:
-          if (!errorIfOutOfDate) {
-            _context2.n = 21;
-            break;
-          }
-          _relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
-          throw new Error("Index file is out of date: ".concat(_relativeIndexPath, "\n") + "Please run the validation command (or next build) locally and commit the updated index files.");
-        case 21:
-          if (fileExists) {
-            _context2.n = 22;
-            break;
-          }
-          _context2.n = 22;
-          return writeFile(indexPath, '', 'utf-8');
-        case 22:
-          mergedPages = []; // Store merged pages for parent update
-          _context2.p = 23;
-          _context2.n = 24;
-          return lockfile.lock(indexPath, _extends({
-            retries: {
-              retries: 300,
-              minTimeout: 1,
-              // Start with 1ms for fast retries
-              maxTimeout: 150,
-              randomize: true
-            },
-            stale: 30000
-          }, lockOptions));
-        case 24:
-          release = _context2.v;
-          // Step 6: Re-read and re-merge to catch any concurrent updates from other processes
-          // This ensures we don't lose updates from other pages being processed in parallel
-          currentContent = '';
-          _context2.p = 25;
-          _context2.n = 26;
-          return readFile(indexPath, 'utf-8');
-        case 26:
-          currentContent = _context2.v;
-          _context2.n = 28;
-          break;
-        case 27:
-          _context2.p = 27;
-          _t3 = _context2.v;
-          if (!(_t3.code !== 'ENOENT')) {
-            _context2.n = 28;
-            break;
-          }
-          throw _t3;
-        case 28:
-          currentMarkdown = currentContent.trim() ? currentContent : undefined;
-          currentPages = [];
-          if (!currentMarkdown) {
-            _context2.n = 30;
-            break;
-          }
-          _context2.n = 29;
-          return markdownToMetadata(currentMarkdown);
-        case 29:
-          _parsed = _context2.v;
-          if (_parsed) {
-            currentPages = _parsed.pages;
-          }
-        case 30:
-          // For batch updates, merge the metadata items with existing pages
-          // Build a map keyed by path (not slug) to match mergeMetadataMarkdown's logic
-          updatedPagesMap = new Map(); // First, add all current pages
-          _iterator4 = _createForOfIteratorHelper(currentPages);
-          try {
-            for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
-              page = _step4.value;
-              updatedPagesMap.set(page.path, page);
-            }
-
-            // Then update/add the new metadata items
-          } catch (err) {
-            _iterator4.e(err);
-          } finally {
-            _iterator4.f();
-          }
-          _iterator5 = _createForOfIteratorHelper(metadataArray);
-          try {
-            for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
-              metaItem = _step5.value;
-              updatedPagesMap.set(metaItem.path, metaItem);
-            }
-
-            // Convert back to array - this is the COMPLETE list of pages that should exist
-          } catch (err) {
-            _iterator5.e(err);
-          } finally {
-            _iterator5.f();
-          }
-          allPages = Array.from(updatedPagesMap.values()); // Store for parent update
-          mergedPages = allPages;
-
-          // Re-merge with the latest content, passing the COMPLETE list of pages
-          // mergeMetadataMarkdown will preserve the order from currentMarkdown
-          // Only include path in the comment when baseDir is set (otherwise it's an absolute path)
-          _relativeIndexPath2 = baseDir ? relative(resolve(baseDir), indexPath) : undefined;
-          _context2.n = 31;
-          return mergeMetadataMarkdown(currentMarkdown, {
-            title: indexTitle,
-            pages: allPages
-          }, {
-            indexWrapperComponent: indexWrapperComponent,
-            path: _relativeIndexPath2
-          });
-        case 31:
-          finalMarkdown = _context2.v;
-          if (!(!finalMarkdown || !finalMarkdown.trim())) {
-            _context2.n = 32;
-            break;
-          }
-          throw new Error("Cannot write empty content to ".concat(indexPath));
-        case 32:
-          if (!(currentContent !== finalMarkdown)) {
-            _context2.n = 35;
-            break;
-          }
-          _context2.n = 33;
-          return writeFile(indexPath, finalMarkdown, 'utf-8');
-        case 33:
-          if (!markerDir) {
-            _context2.n = 35;
-            break;
-          }
-          // Compute relative path for marker (always compute, not used for comments)
-          markerRelativePath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath; // Resolve markerDir relative to baseDir (if baseDir is provided)
-          markerDirResolved = baseDir ? resolve(baseDir, markerDir) : markerDir;
-          markerPath = join(markerDirResolved, markerRelativePath);
-          markerDirPath = dirname(markerPath); // Ensure the marker directory exists
-          _context2.n = 34;
-          return mkdir(markerDirPath, {
-            recursive: true
-          });
-        case 34:
-          _context2.n = 35;
-          return writeFile(markerPath, '', 'utf-8');
-        case 35:
-          _context2.p = 35;
-          if (!release) {
-            _context2.n = 36;
-            break;
-          }
-          _context2.n = 36;
-          return release();
-        case 36:
-          return _context2.f(35);
-        case 37:
-          if (!(updateParents && !shouldStop)) {
-            _context2.n = 47;
-            break;
-          }
-          // Get the grandparent directory, skipping over Next.js route groups
-          grandParentDir = getParentDir(parentDir, true); // Only continue if we're not at the filesystem root
-          if (!(grandParentDir !== parentDir)) {
-            _context2.n = 47;
-            break;
-          }
-          // CRITICAL: Use the merged pages from Step 6, not a re-read of the file
-          // Re-reading could get a stale version if other processes are still writing
-          // mergedPages already contains ALL pages after the merge in Step 6
-          // Calculate the relative path from grandparent to this index, preserving route groups
-          relativePathFromGrandparent = relative(grandParentDir, parentDir); // Extract metadata for the current index to add to its parent
-          indexMetadata = {
-            slug: basename(parentDir),
-            path: "./".concat(relativePathFromGrandparent, "/").concat(indexFileName),
-            title: indexTitle,
-            description: 'No description available'
-          }; // Convert child pages to sections format (no subsections, just page names)
-          // Use mergedPages which contains the complete merged state
-          // Skip single-link entries (external links) as they don't have detail sections
-          if (!(mergedPages.length > 0)) {
-            _context2.n = 46;
-            break;
-          }
-          sections = {};
-          _iterator6 = _createForOfIteratorHelper(mergedPages);
-          _context2.p = 38;
-          _iterator6.s();
-        case 39:
-          if ((_step6 = _iterator6.n()).done) {
-            _context2.n = 42;
-            break;
-          }
-          childPage = _step6.value;
-          if (!childPage.skipDetailSection) {
-            _context2.n = 40;
-            break;
+export async function syncPageIndex(options) {
+  const {
+    pagePath,
+    metadata,
+    metadataList,
+    indexFileName = 'page.mdx',
+    lockOptions = {},
+    baseDir,
+    updateParents = false,
+    include,
+    exclude,
+    onlyUpdateIndexes = false,
+    markerDir = false,
+    errorIfOutOfDate = false,
+    indexWrapperComponent
+  } = options;
+
+  // Validate that either metadata or metadataList is provided
+  if (!metadata && (!metadataList || metadataList.length === 0)) {
+    throw new Error('Either metadata or metadataList must be provided');
+  }
+
+  // Determine if we're doing a batch update
+  const isBatchUpdate = !!metadataList;
+  const metadataArray = isBatchUpdate ? metadataList : [metadata];
+
+  // Resolve the index file path
+  // For batch updates, pagePath is the index file itself
+  // For single updates, pagePath is a child page and we need the parent's index
+  const indexPath = isBatchUpdate ? resolve(pagePath) : resolve(getParentDir(dirname(pagePath), true), indexFileName);
+  const parentDir = dirname(indexPath);
+
+  // Check if this index path should be processed based on include/exclude filters
+  if (baseDir) {
+    const relativePath = relative(resolve(baseDir), resolve(parentDir));
+    if (!shouldIncludePath(relativePath, include, exclude)) {
+      // This index is outside the configured paths - skip it
+      return;
+    }
+  }
+
+  // Check if we've reached the base directory
+  const shouldStop = baseDir && resolve(parentDir) === resolve(baseDir);
+
+  // Derive index title from directory name if not provided
+  const indexTitle = options.indexTitle ?? kebabToTitleCase(basename(parentDir));
+
+  // Step 1: Read the file without acquiring a lock to check if we need to make changes
+  let existingContent = '';
+  let fileExists = true;
+  try {
+    existingContent = await readFile(indexPath, 'utf-8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+    // File doesn't exist
+    fileExists = false;
+
+    // If onlyUpdateIndexes is true and file doesn't exist, skip this update
+    if (onlyUpdateIndexes) {
+      return;
+    }
+
+    // If errorIfOutOfDate is true, throw an error for missing index
+    if (errorIfOutOfDate) {
+      const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
+      throw new Error(`Index file is missing: ${relativeIndexPath}\n` + `Please run next build locally and commit the updated index files.\n` + `Don't forget to add it to the \`app/sitemap/index.ts\` to list it publicly.`);
+    }
+  }
+
+  // Step 1.5: Verify the file has the autogeneration marker if it exists
+  if (fileExists && existingContent) {
+    const hasMarker = existingContent.includes("[//]: # 'This file is autogenerated");
+    if (!hasMarker) {
+      // File exists but doesn't have the autogeneration marker - skip updating it
+      return;
+    }
+  }
+
+  // Step 2: Parse existing content and check if our specific page needs updating
+  const existingMarkdown = existingContent.trim() ? existingContent : undefined;
+  let existingPages = [];
+  if (existingMarkdown) {
+    const parsed = await markdownToMetadata(existingMarkdown);
+    if (parsed) {
+      existingPages = parsed.pages;
+    }
+  }
+
+  // Step 3: Check if any of our metadata items need updating
+  let needsUpdate = false;
+  for (const metaItem of metadataArray) {
+    const existingPageIndex = existingPages.findIndex(p => p.slug === metaItem.slug);
+    if (existingPageIndex >= 0) {
+      const existingPage = existingPages[existingPageIndex];
+      // Compare metadata - if different, we need to update
+      const existingPageJson = JSON.stringify(existingPage);
+      const newPageJson = JSON.stringify(metaItem);
+      if (existingPageJson !== newPageJson) {
+        needsUpdate = true;
+        break;
+      }
+    } else {
+      // Page doesn't exist, we need to add it
+      needsUpdate = true;
+      break;
+    }
+  }
+  if (!needsUpdate) {
+    // All pages are already up-to-date, no need to acquire lock or write
+    return;
+  }
+
+  // If errorIfOutOfDate is true, throw an error instead of updating
+  if (errorIfOutOfDate) {
+    const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
+    throw new Error(`Index file is out of date: ${relativeIndexPath}\n` + `Please run the validation command (or next build) locally and commit the updated index files.`);
+  }
+
+  // Step 4: Ensure the file exists before locking (proper-lockfile requires an existing file)
+  if (!fileExists) {
+    await writeFile(indexPath, '', 'utf-8');
+  }
+  let release;
+  let mergedPages = []; // Store merged pages for parent update
+
+  try {
+    // Step 5: Acquire lock on the index file
+    release = await lockfile.lock(indexPath, {
+      retries: {
+        retries: 300,
+        minTimeout: 1,
+        // Start with 1ms for fast retries
+        maxTimeout: 150,
+        randomize: true
+      },
+      stale: 30000,
+      ...lockOptions
+    });
+
+    // Step 6: Re-read and re-merge to catch any concurrent updates from other processes
+    // This ensures we don't lose updates from other pages being processed in parallel
+    let currentContent = '';
+    try {
+      currentContent = await readFile(indexPath, 'utf-8');
+    } catch (error) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+      // File was deleted while waiting - that's okay, we'll create it
+    }
+    const currentMarkdown = currentContent.trim() ? currentContent : undefined;
+    let currentPages = [];
+    if (currentMarkdown) {
+      const parsed = await markdownToMetadata(currentMarkdown);
+      if (parsed) {
+        currentPages = parsed.pages;
+      }
+    }
+
+    // For batch updates, merge the metadata items with existing pages
+    // Build a map keyed by path (not slug) to match mergeMetadataMarkdown's logic
+    const updatedPagesMap = new Map();
+
+    // First, add all current pages
+    for (const page of currentPages) {
+      updatedPagesMap.set(page.path, page);
+    }
+
+    // Then update/add the new metadata items
+    for (const metaItem of metadataArray) {
+      updatedPagesMap.set(metaItem.path, metaItem);
+    }
+
+    // Convert back to array - this is the COMPLETE list of pages that should exist
+    const allPages = Array.from(updatedPagesMap.values());
+
+    // Store for parent update
+    mergedPages = allPages;
+
+    // Re-merge with the latest content, passing the COMPLETE list of pages
+    // mergeMetadataMarkdown will preserve the order from currentMarkdown
+    // Only include path in the comment when baseDir is set (otherwise it's an absolute path)
+    const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : undefined;
+    const finalMarkdown = await mergeMetadataMarkdown(currentMarkdown, {
+      title: indexTitle,
+      pages: allPages
+    }, {
+      indexWrapperComponent,
+      path: relativeIndexPath
+    });
+
+    // Defensive check
+    if (!finalMarkdown || !finalMarkdown.trim()) {
+      throw new Error(`Cannot write empty content to ${indexPath}`);
+    }
+
+    // Step 7: Write only if the final content differs from what's currently on disk
+    if (currentContent !== finalMarkdown) {
+      await writeFile(indexPath, finalMarkdown, 'utf-8');
+
+      // Create a marker file unless explicitly disabled
+      if (markerDir) {
+        // Compute relative path for marker (always compute, not used for comments)
+        const markerRelativePath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
+        // Resolve markerDir relative to baseDir (if baseDir is provided)
+        const markerDirResolved = baseDir ? resolve(baseDir, markerDir) : markerDir;
+        const markerPath = join(markerDirResolved, markerRelativePath);
+        const markerDirPath = dirname(markerPath);
+
+        // Ensure the marker directory exists
+        await mkdir(markerDirPath, {
+          recursive: true
+        });
+
+        // Create an empty marker file
+        await writeFile(markerPath, '', 'utf-8');
+      }
+    }
+  } finally {
+    // Always release the lock
+    if (release) {
+      await release();
+    }
+  }
+
+  // After releasing the lock, update the parent index if needed
+  if (updateParents && !shouldStop) {
+    // Get the grandparent directory, skipping over Next.js route groups
+    const grandParentDir = getParentDir(parentDir, true);
+
+    // Only continue if we're not at the filesystem root
+    if (grandParentDir !== parentDir) {
+      // CRITICAL: Use the merged pages from Step 6, not a re-read of the file
+      // Re-reading could get a stale version if other processes are still writing
+      // mergedPages already contains ALL pages after the merge in Step 6
+
+      // Calculate the relative path from grandparent to this index, preserving route groups
+      const relativePathFromGrandparent = relative(grandParentDir, parentDir);
+
+      // Extract metadata for the current index to add to its parent
+      const indexMetadata = {
+        slug: basename(parentDir),
+        path: `./${relativePathFromGrandparent}/${indexFileName}`,
+        title: indexTitle,
+        description: 'No description available'
+      };
+
+      // Convert child pages to sections format (no subsections, just page names)
+      // Use mergedPages which contains the complete merged state
+      // Skip single-link entries (external links) as they don't have detail sections
+      if (mergedPages.length > 0) {
+        const sections = {};
+        for (const childPage of mergedPages) {
+          // Skip entries that don't have detail sections (external links, etc.)
+          if (childPage.skipDetailSection) {
+            continue;
           }
-          return _context2.a(3, 41);
-        case 40:
           sections[childPage.slug] = {
             title: childPage.title || childPage.slug,
             titleMarkdown: childPage.title ? [{
@@ -500,41 +370,24 @@ function _syncPageIndex() {
             }],
             children: {} // Don't include any subsections in parent index
           };
-        case 41:
-          _context2.n = 39;
-          break;
-        case 42:
-          _context2.n = 44;
-          break;
-        case 43:
-          _context2.p = 43;
-          _t4 = _context2.v;
-          _iterator6.e(_t4);
-        case 44:
-          _context2.p = 44;
-          _iterator6.f();
-          return _context2.f(44);
-        case 45:
-          indexMetadata.sections = sections;
-        case 46:
-          _context2.n = 47;
-          return syncPageIndex({
-            pagePath: indexPath,
-            metadata: indexMetadata,
-            indexFileName: indexFileName,
-            lockOptions: lockOptions,
-            baseDir: baseDir,
-            updateParents: true,
-            include: include,
-            exclude: exclude,
-            onlyUpdateIndexes: onlyUpdateIndexes,
-            markerDir: markerDir,
-            errorIfOutOfDate: errorIfOutOfDate
-          });
-        case 47:
-          return _context2.a(2);
+        }
+        indexMetadata.sections = sections;
       }
-    }, _callee, null, [[38, 43, 44, 45], [25, 27], [23,, 35, 37], [12, 17, 18, 19], [3, 5]]);
-  }));
-  return _syncPageIndex.apply(this, arguments);
+
+      // Recursively update the parent index (will create it if it doesn't exist)
+      await syncPageIndex({
+        pagePath: indexPath,
+        metadata: indexMetadata,
+        indexFileName,
+        lockOptions,
+        baseDir,
+        updateParents: true,
+        include,
+        exclude,
+        onlyUpdateIndexes,
+        markerDir,
+        errorIfOutOfDate
+      });
+    }
+  }
 }