Fix cache rebuild guard to use birthtimeMs instead of mtimeMs

Author: ababilone

packages/sdk/src/internal/resources.ts

@@ -20,13 +20,10 @@ export const versionResource = async (catalogDir: string, id: string) => {
     throw new Error(`No resource found with id: ${id}`);
   }
 
-  // Event that is in the route of the project
   const file = matchedFiles[0];
-  // Handle both forward and back slashes for cross-platform compatibility (Windows uses \, Unix uses /)
   const sourceDirectory = dirname(file).replace(/[/\\]versioned[/\\][^/\\]+[/\\]/, path.sep);
   const { data: { version = '0.0.1' } = {} } = matter.read(file);
   const targetDirectory = getVersionedDirectory(sourceDirectory, version);
-
   fsSync.mkdirSync(targetDirectory, { recursive: true });
 
   const ignoreListToCopy = ['events', 'commands', 'queries', 'versioned'];
@@ -72,7 +69,6 @@ export const versionResource = async (catalogDir: string, id: string) => {
   }
   // 2. Add the newly created versioned copy
   if (rootParsed) {
-    const { data: { version: ver = '0.0.1' } = {} } = rootParsed;
     const versionedIndexFile = fsSync.existsSync(join(targetDirectory, 'index.mdx'))
       ? join(targetDirectory, 'index.mdx')
       : join(targetDirectory, 'index.md');
@@ -95,13 +91,12 @@ export const writeResource = async (
 ) => {
   const path = options.path || `/${resource.id}`;
   const fullPath = join(catalogDir, path);
-  const format = options.format || 'mdx';
 
   // Create directory if it doesn't exist
   fsSync.mkdirSync(fullPath, { recursive: true });
 
   // Create or get lock file path
-  const lockPath = join(fullPath, `index.${format}`);
+  const lockPath = join(fullPath, `index.${options.format || 'mdx'}`);
 
   // Ensure the file exists before attempting to lock it
   if (!fsSync.existsSync(lockPath)) {

packages/sdk/src/internal/utils.ts

@@ -16,7 +16,10 @@ interface FileIndexEntry {
 let _fileIndexCache: Map<string, FileIndexEntry[]> | null = null;
 let _fileIndexCatalogDir: string | null = null;
 let _matterCache: Map<string, matter.GrayMatterFile<string>> | null = null;
-let _fileIndexMtimeMs: number = 0;
+// Tracks the creation time (birthtimeMs) of the catalog directory at last cache build.
+// birthtimeMs only changes when the directory is deleted and recreated (e.g. test teardown),
+// making it a reliable guard that avoids spurious rebuilds from nested write operations.
+let _fileIndexDirBirthtimeMs: number = 0;
 
 function buildFileCache(catalogDir: string): void {
   const files = globSync('**/index.{md,mdx}', {
@@ -53,9 +56,9 @@ function buildFileCache(catalogDir: string): void {
   _fileIndexCatalogDir = catalogDir;
   _matterCache = matterResults;
   try {
-    _fileIndexMtimeMs = fsSync.statSync(catalogDir).mtimeMs;
+    _fileIndexDirBirthtimeMs = fsSync.statSync(catalogDir).birthtimeMs;
   } catch {
-    _fileIndexMtimeMs = 0;
+    _fileIndexDirBirthtimeMs = 0;
   }
 }
 
@@ -64,10 +67,12 @@ function ensureFileCache(catalogDir: string): void {
     buildFileCache(catalogDir);
     return;
   }
-  // Check if catalog dir was recreated (e.g. tests wiping and recreating)
+  // Rebuild if the catalog directory was deleted and recreated (birthtimeMs changes on recreation).
+  // Unlike mtimeMs, birthtimeMs is unaffected by nested file/directory writes, so it won't
+  // trigger spurious rebuilds during normal catalog operations.
   try {
-    const currentMtime = fsSync.statSync(catalogDir).mtimeMs;
-    if (currentMtime !== _fileIndexMtimeMs) {
+    const currentBirthtime = fsSync.statSync(catalogDir).birthtimeMs;
+    if (currentBirthtime !== _fileIndexDirBirthtimeMs) {
       buildFileCache(catalogDir);
     }
   } catch {
@@ -198,7 +203,48 @@ export const findFileById = async (catalogDir: string, id: string, version?: str
   return undefined;
 };
 
+/**
+ * Converts a glob pattern to a RegExp. Handles `**`, `*`, `{a,b}` and `.` escaping.
+ * Sufficient for the limited patterns used in getFiles.
+ */
+function globToRegex(pattern: string): RegExp {
+  const normalized = pattern.replace(/\\/g, '/');
+  const regexStr = normalized
+    .replace(/[.+^${}()|[\]\\]/g, (ch) => {
+      // Keep { } and handle them specially below; escape everything else
+      if (ch === '{' || ch === '}') return ch;
+      return `\\${ch}`;
+    })
+    .replace(/\{([^}]+)\}/g, (_, choices) => `(${choices.split(',').join('|')})`)
+    .replace(/\*\*/g, '\u0000') // temp placeholder
+    .replace(/\*/g, '[^/]*')
+    .replace(/\u0000\//g, '(?:.+/)?') // **/ → optional nested path
+    .replace(/\u0000/g, '.*'); // remaining ** (at end)
+  return new RegExp(`^${regexStr}$`, 'i');
+}
+
 export const getFiles = async (pattern: string, ignore: string | string[] = '') => {
+  // Fast path: if the file index cache is warm for this catalog dir, filter cached
+  // paths by the pattern instead of performing an expensive glob on the file system.
+  // Only applies when the pattern targets index.{md,mdx} files — the cache only
+  // stores those files, so non-index patterns (e.g. teams/*.md) must fall through.
+  if (_fileIndexCache && _matterCache && _fileIndexCatalogDir) {
+    const normalizedCatalogDir = normalize(_fileIndexCatalogDir).replace(/\\/g, '/');
+    const normalizedPattern = normalize(pattern).replace(/\\/g, '/');
+    if (
+      normalizedPattern.startsWith(normalizedCatalogDir) &&
+      normalizedPattern.includes('index.{md,mdx}')
+    ) {
+      const ignoreList = (Array.isArray(ignore) ? ignore : [ignore]).filter(Boolean);
+      const matchRegex = globToRegex(normalizedPattern);
+      const ignoreRegexes = ignoreList.map((ig) => globToRegex(ig.replace(/\\/g, '/')));
+      return Array.from(_matterCache.keys())
+        .map((p) => p.replace(/\\/g, '/'))
+        .filter((p) => matchRegex.test(p) && !ignoreRegexes.some((ig) => ig.test(p)))
+        .map(normalize);
+    }
+  }
+
   try {
     // 1. Normalize the input pattern to handle mixed separators potentially
     const normalizedInputPattern = normalize(pattern);
@@ -252,10 +298,27 @@ export const readMdxFile = async (path: string) => {
 };
 
 export const searchFilesForId = async (files: string[], id: string, version?: string) => {
-  // Escape the id to avoid regex issues
+  // Fast path: if the file index cache is warm we can resolve by id directly
+  // without reading any files from disk — O(1) map lookup + set intersection.
+  if (_fileIndexCache) {
+    const entries = _fileIndexCache.get(id);
+    if (entries) {
+      const filesSet = new Set(files.map(normalize));
+      return entries
+        .filter((e) => {
+          if (!filesSet.has(e.path)) return false;
+          if (version && e.version !== version) return false;
+          return true;
+        })
+        .map((e) => e.path);
+    }
+    // id not found in cache means no match in these files
+    return [];
+  }
+
+  // Slow path: read each file from disk and match by id/version regex
   const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   const idRegex = new RegExp(`^id:\\s*(['"]|>-)?\\s*${escapedId}['"]?\\s*$`, 'm');
-
   const versionRegex = new RegExp(`^version:\\s*['"]?${version}['"]?\\s*$`, 'm');
 
   const matches = files.map((file) => {