fix(notion-fetch): improve logging and timeout for skipped content (Phase 1)

Phase 1 of fixing issue #95: Content being skipped during fetch

Changes:
1. Add detailed skip reason logging in generateBlocks.ts
   - Shows specific reason why each page is skipped (cache hit, timestamp, path change, etc.)
   - Helps diagnose incorrect skip behavior
   - Includes "should not skip" warnings for potential bugs

2. Enhanced sub-page timeout error logging in fetchNotionData.ts
   - Display error type and detailed message
   - Add helpful hints when timeout occurs
   - Better categorization of failures (timeout vs API error vs permission)

3. Increase sub-page fetch timeout from 10s to 30s
   - Handles slow Notion API responses better
   - Reduces false positive timeouts for complex pages
   - Particularly helpful for pages with large blocks or nested children

Benefits:
- Immediate diagnostic value for debugging skipped pages
- Fewer legitimate pages timing out and being skipped
- Clear visibility into incremental sync behavior

Related: ISSUE_95_PLAN.md

Author: claude

scripts/fetchNotionData.ts

@@ -186,7 +186,9 @@ export async function sortAndExpandNotionData(
           try {
             // Add explicit timeout to prevent hanging indefinitely
             // GitHub Actions seems to have issues with Notion API calls hanging
-            const TIMEOUT_MS = 10000; // 10 second timeout
+            // Increased from 10s to 30s to handle slow Notion API responses,
+            // particularly for pages with large blocks or many nested children
+            const TIMEOUT_MS = 30000; // 30 second timeout
             const timeoutPromise = new Promise((_resolve, reject) =>
               setTimeout(
                 () =>
@@ -221,9 +223,28 @@ export async function sortAndExpandNotionData(
           } catch (pageError) {
             // Log the error but don't let it fail the entire batch
             // Timeouts and individual page failures should be handled gracefully
+            const errorMessage =
+              pageError instanceof Error
+                ? pageError.message
+                : String(pageError);
+            const errorType =
+              pageError instanceof Error
+                ? pageError.constructor.name
+                : typeof pageError;
+            const isTimeout = errorMessage.toLowerCase().includes("timeout");
+
             console.warn(
-              `⚠️  Skipping sub-page ${rel.subId} (parent: "${rel.parentTitle}"): ${pageError.message}`
+              `⚠️  Skipping sub-page ${rel.subId} (parent: "${rel.parentTitle}")`
             );
+            console.warn(`    Error: ${errorMessage}`);
+            console.warn(`    Type: ${errorType}`);
+
+            if (isTimeout) {
+              console.warn(
+                `    💡 Hint: This page timed out. Consider increasing TIMEOUT_MS in fetchNotionData.ts`
+              );
+            }
+
             return null; // Return null for failed pages, filter them out later
           }
         })

scripts/notion-fetch/generateBlocks.ts

@@ -712,9 +712,29 @@ export async function generateBlocks(
 
           if (!needsProcessing) {
             // Page unchanged, skip processing but still count it
-            console.log(
-              chalk.gray(`  ⏭️  Skipping unchanged page: ${pageTitle}`)
-            );
+            // Determine the specific reason for skipping (for diagnostics)
+            let skipReason: string;
+            if (syncMode.fullRebuild) {
+              // This condition can't be reached if !needsProcessing, but for completeness
+              skipReason = "full rebuild mode";
+            } else if (!cachedPage) {
+              skipReason = "not in cache (NEW PAGE - should not skip)";
+            } else if (hasMissingOutputs(metadataCache, page.id)) {
+              skipReason = "missing output files (should not skip)";
+            } else if (!cachedPage.outputPaths?.includes(filePath)) {
+              skipReason = `path changed from [${cachedPage.outputPaths?.join(", ") || "none"}] to [${filePath}] (should not skip)`;
+            } else {
+              const notionTime = new Date(page.last_edited_time).getTime();
+              const cachedTime = new Date(cachedPage.lastEdited).getTime();
+              if (notionTime > cachedTime) {
+                skipReason = `timestamp updated (${page.last_edited_time} > ${cachedPage.lastEdited}) (should not skip)`;
+              } else {
+                skipReason = `unchanged since ${cachedPage.lastEdited}`;
+              }
+            }
+
+            console.log(chalk.gray(`  ⏭️  Skipping page: ${pageTitle}`));
+            console.log(chalk.dim(`      Reason: ${skipReason}`));
             processedPages++;
             progressCallback({ current: processedPages, total: totalPages });
           } else if (dryRun) {