refactor: extract shared file and path utilities

- Create shared/file.utils.ts for safe file operations
- Create shared/path.utils.ts for path manipulation
- Refactor 6 modules to use shared utilities
- Add comprehensive tests and implementation plan

Eliminates duplicate file reading patterns and path matching logic.

close #31

Author: wishket-pjw

docs/plans/REFACTOR-001-implementation-plan.md

@@ -0,0 +1,135 @@
+# REFACTOR-001 Implementation Plan
+
+## Analysis Summary
+
+### Issue 1: File Reading Pattern Duplication
+
+**Originally estimated**: 3 locations
+**Actually found**: 6 locations (+ 3 additional in config.analyzer.ts)
+
+| Module | Pattern | Return on Error |
+|--------|---------|-----------------|
+| ignore.parser.ts | readFile → catch → return empty | `{ patterns: [], source: null }` |
+| context.loader.ts (loadContextFile) | readFile → catch → return null | `null` |
+| context.loader.ts (getAllFiles) | readdir → catch → skip | (continues) |
+| code.sampler.ts | stat + readFile → catch → skip | (continues) |
+| package.analyzer.ts | readFile → catch → return null | `null` |
+| config.analyzer.ts | readFile → catch → skip (×3) | (continues) |
+
+**Key observation**: None check for ENOENT specifically. All use bare `catch` blocks.
+
+### Issue 2: Path Matching Logic Duplication
+
+| Pattern Type | Location | Approach |
+|--------------|----------|----------|
+| Path separator handling | code.sampler.ts | Check both `/` and `\` manually |
+| Path separator handling | ignore.parser.ts | Normalize `\` to `/` upfront |
+| Wildcard matching | config.analyzer.ts | Simple `*` → `.*` regex |
+| Glob pattern matching | ignore.parser.ts | Full gitignore-style (**, !, anchors) |
+| Directory in path check | code.sampler.ts | Custom `pathContainsDir()` helper |
+| Directory in path check | directory.analyzer.ts | Inline string checks |
+
+---
+
+## Implementation Plan
+
+### Phase 1: Create Shared File Utilities
+
+**Goal**: Consolidate file reading patterns into reusable utilities
+
+**New module**: `src/shared/file.utils.ts`
+
+**Functions to create**:
+
+1. `safeReadFile(path): Promise<string | null>`
+   - Returns file content or null if not found
+   - Throws on permission/other errors
+
+2. `safeReadFileWithFallback<T>(path, fallback): Promise<T>`
+   - Returns parsed content or fallback value
+   - Useful for config files with default empty objects
+
+3. `tryReadFile(path): Promise<string | undefined>`
+   - Silent failure variant for skip-on-error patterns
+
+**Refactoring targets** (6 files):
+- `src/config/ignore.parser.ts`
+- `src/config/context.loader.ts`
+- `src/analyzer/code.sampler.ts`
+- `src/analyzer/package.analyzer.ts`
+- `src/analyzer/config.analyzer.ts`
+
+### Phase 2: Create Shared Path Utilities
+
+**Goal**: Unify path matching approaches
+
+**New module**: `src/shared/path.utils.ts`
+
+**Functions to create**:
+
+1. `normalizePath(path): string`
+   - Converts all `\` to `/`
+   - Single source of truth for path normalization
+
+2. `pathContainsSegment(path, segment): boolean`
+   - Checks if path contains a directory segment
+   - Replaces manual `/dir/` and `\dir\` checks
+
+3. `matchesGlobPattern(path, pattern): boolean`
+   - Wrapper around existing `patternToRegex` in ignore.parser.ts
+   - Reusable for config.analyzer.ts wildcard matching
+
+**Refactoring targets** (3 files):
+- `src/analyzer/code.sampler.ts`
+- `src/analyzer/config.analyzer.ts`
+- `src/analyzer/directory.analyzer.ts`
+
+---
+
+## Execution Order
+
+```
+Step 1: Create src/shared/file.utils.ts + tests
+        ↓
+Step 2: Refactor config/ modules to use file.utils
+        ↓
+Step 3: Refactor analyzer/ modules to use file.utils
+        ↓
+Step 4: Create src/shared/path.utils.ts + tests
+        ↓
+Step 5: Refactor analyzer/ modules to use path.utils
+        ↓
+Step 6: Run full test suite, verify 269+ tests pass
+```
+
+---
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Breaking error handling behavior | Keep same return types (null, empty object, skip) |
+| Missing edge cases | Existing tests cover current behavior |
+| Import cycle | shared/ has no dependencies on config/ or analyzer/ |
+
+---
+
+## Success Metrics
+
+- [ ] `safeReadFile` pattern used in all 6 locations
+- [ ] `normalizePath` used consistently for path operations
+- [ ] No duplicate file reading try-catch blocks remain
+- [ ] No duplicate path separator handling remains
+- [ ] All 269 existing tests pass
+- [ ] New utility functions have dedicated test coverage
+
+---
+
+## Estimated Scope
+
+| Item | Count |
+|------|-------|
+| New files | 4 (2 utils + 2 spec files) |
+| Modified files | 6 |
+| New functions | 5-6 |
+| Risk level | Low |

mcp-server/src/analyzer/code.sampler.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import type { CodeSample, CodeCategory } from './analyzer.types';
+import { pathContainsSegment } from '../shared/path.utils';
 
 /**
  * Language detection by file extension
@@ -125,18 +126,6 @@ export function isCodeFile(filePath: string): boolean {
   return CODE_EXTENSIONS.has(ext);
 }
 
-/**
- * Check if path contains a directory (handles both /dir/ and dir/ at start)
- */
-function pathContainsDir(lowerPath: string, dirName: string): boolean {
-  return (
-    lowerPath.includes(`/${dirName}/`) ||
-    lowerPath.includes(`\\${dirName}\\`) ||
-    lowerPath.startsWith(`${dirName}/`) ||
-    lowerPath.startsWith(`${dirName}\\`)
-  );
-}
-
 /**
  * Categorize a file based on its path and name
  */
@@ -156,25 +145,25 @@ export function categorizeFile(filePath: string): CodeCategory {
 
   // API/Route files (check before hooks to avoid false positives like 'users.ts')
   if (
-    pathContainsDir(lower, 'api') ||
+    pathContainsSegment(filePath, 'api') ||
     fileName === 'route.ts' ||
     fileName === 'route.js'
   ) {
     return 'api';
   }
 
   // Service files
-  if (pathContainsDir(lower, 'services') || fileName.includes('.service.')) {
+  if (pathContainsSegment(filePath, 'services') || fileName.includes('.service.')) {
     return 'service';
   }
 
   // Model/Entity files
-  if (pathContainsDir(lower, 'models') || pathContainsDir(lower, 'entities')) {
+  if (pathContainsSegment(filePath, 'models') || pathContainsSegment(filePath, 'entities')) {
     return 'model';
   }
 
   // Hook files (React hooks pattern - useXxx where X is uppercase)
-  if (pathContainsDir(lower, 'hooks')) {
+  if (pathContainsSegment(filePath, 'hooks')) {
     return 'hook';
   }
   // Check for useXxx pattern (use followed by uppercase letter)
@@ -184,13 +173,13 @@ export function categorizeFile(filePath: string): CodeCategory {
   }
 
   // Component files
-  if (pathContainsDir(lower, 'components') || pathContainsDir(lower, 'ui')) {
+  if (pathContainsSegment(filePath, 'components') || pathContainsSegment(filePath, 'ui')) {
     return 'component';
   }
 
   // Page files
   if (
-    pathContainsDir(lower, 'pages') ||
+    pathContainsSegment(filePath, 'pages') ||
     fileName === 'page.tsx' ||
     fileName === 'page.ts' ||
     fileName === 'page.jsx' ||
@@ -201,15 +190,15 @@ export function categorizeFile(filePath: string): CodeCategory {
 
   // Utility files
   if (
-    pathContainsDir(lower, 'utils') ||
-    pathContainsDir(lower, 'lib') ||
-    pathContainsDir(lower, 'helpers')
+    pathContainsSegment(filePath, 'utils') ||
+    pathContainsSegment(filePath, 'lib') ||
+    pathContainsSegment(filePath, 'helpers')
   ) {
     return 'util';
   }
 
   // Config files
-  if (pathContainsDir(lower, 'config')) {
+  if (pathContainsSegment(filePath, 'config')) {
     return 'config';
   }
 

mcp-server/src/analyzer/config.analyzer.ts

@@ -1,4 +1,3 @@
-import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import type {
@@ -7,6 +6,7 @@ import type {
   EslintSummary,
   PrettierSummary,
 } from './analyzer.types';
+import { tryReadFile } from '../shared/file.utils';
 
 /**
  * Known config file patterns by type
@@ -171,15 +171,13 @@ export async function analyzeConfigs(
     if (!pattern.includes('*')) {
       const filePath = path.join(projectRoot, pattern);
       if (existsSync(filePath)) {
-        try {
-          const content = await fs.readFile(filePath, 'utf-8');
+        const content = await tryReadFile(filePath);
+        if (content !== undefined) {
           const parsed = parseTsConfig(content, pattern);
           if (parsed) {
             result.typescript = parsed;
             break;
           }
-        } catch {
-          // Ignore read errors
         }
       }
     }
@@ -190,15 +188,13 @@ export async function analyzeConfigs(
   for (const fileName of eslintJsonFiles) {
     const filePath = path.join(projectRoot, fileName);
     if (existsSync(filePath)) {
-      try {
-        const content = await fs.readFile(filePath, 'utf-8');
+      const content = await tryReadFile(filePath);
+      if (content !== undefined) {
         const parsed = parseEslintConfig(content, fileName, getEslintFormat(fileName));
         if (parsed) {
           result.eslint = parsed;
           break;
         }
-      } catch {
-        // Ignore read errors
       }
     }
   }
@@ -221,15 +217,13 @@ export async function analyzeConfigs(
   for (const fileName of prettierJsonFiles) {
     const filePath = path.join(projectRoot, fileName);
     if (existsSync(filePath)) {
-      try {
-        const content = await fs.readFile(filePath, 'utf-8');
+      const content = await tryReadFile(filePath);
+      if (content !== undefined) {
         const parsed = parsePrettierConfig(content, fileName);
         if (parsed) {
           result.prettier = parsed;
           break;
         }
-      } catch {
-        // Ignore read errors
       }
     }
   }

mcp-server/src/analyzer/directory.analyzer.ts

@@ -1,8 +1,8 @@
-import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import type { DirectoryAnalysis, ArchitecturePattern } from './analyzer.types';
 import { shouldIgnore, getDefaultIgnorePatterns } from '../config/ignore.parser';
+import { safeReadDirWithTypes } from '../shared/file.utils';
 
 /**
  * Architecture pattern definition
@@ -157,32 +157,28 @@ async function scanDirectory(
     return { files, dirs };
   }
 
-  try {
-    const entries = await fs.readdir(currentPath, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const entryRelativePath = relativePath
-        ? `${relativePath}/${entry.name}`
-        : entry.name;
-
-      // Check if should be ignored
-      if (shouldIgnore(entryRelativePath, ignorePatterns)) {
-        continue;
-      }
-
-      if (entry.isDirectory()) {
-        dirs.push(entryRelativePath);
-
-        // Recursively scan subdirectories
-        const subResult = await scanDirectory(rootPath, ignorePatterns, entryRelativePath);
-        files.push(...subResult.files);
-        dirs.push(...subResult.dirs);
-      } else if (entry.isFile()) {
-        files.push(entryRelativePath);
-      }
+  const entries = await safeReadDirWithTypes(currentPath);
+
+  for (const entry of entries) {
+    const entryRelativePath = relativePath
+      ? `${relativePath}/${entry.name}`
+      : entry.name;
+
+    // Check if should be ignored
+    if (shouldIgnore(entryRelativePath, ignorePatterns)) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      dirs.push(entryRelativePath);
+
+      // Recursively scan subdirectories
+      const subResult = await scanDirectory(rootPath, ignorePatterns, entryRelativePath);
+      files.push(...subResult.files);
+      dirs.push(...subResult.dirs);
+    } else if (entry.isFile()) {
+      files.push(entryRelativePath);
     }
-  } catch {
-    // Ignore permission errors
   }
 
   return { files, dirs };

mcp-server/src/analyzer/package.analyzer.ts

@@ -1,11 +1,11 @@
-import * as fs from 'fs/promises';
 import { existsSync } from 'fs';
 import * as path from 'path';
 import type {
   PackageInfo,
   DetectedFramework,
   FrameworkCategory,
 } from './analyzer.types';
+import { safeReadFile } from '../shared/file.utils';
 
 /**
  * Framework detection definition
@@ -171,8 +171,13 @@ export async function analyzePackage(projectRoot: string): Promise<PackageInfo |
     return null;
   }
 
+  const content = await safeReadFile(packagePath);
+
+  if (content === null) {
+    return null;
+  }
+
   try {
-    const content = await fs.readFile(packagePath, 'utf-8');
     const parsed = parsePackageJson(content);
     const frameworks = detectFrameworks(parsed.dependencies, parsed.devDependencies);