mdcontext 0.1.0 → 0.2.0

package/src/index/storage.ts

@@ -7,6 +7,12 @@ import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import { Effect } from 'effect'
 
+import {
+  DirectoryCreateError,
+  FileReadError,
+  FileWriteError,
+  IndexCorruptedError,
+} from '../errors/index.js'
 import type {
   DocumentIndex,
   IndexConfig,
@@ -19,35 +25,82 @@ import { getIndexPaths, INDEX_VERSION } from './types.js'
 // File System Helpers
 // ============================================================================
 
-const ensureDir = (dirPath: string): Effect.Effect<void, Error> =>
+const ensureDir = (
+  dirPath: string,
+): Effect.Effect<void, DirectoryCreateError> =>
   Effect.tryPromise({
     try: () => fs.mkdir(dirPath, { recursive: true }),
-    catch: (e) => new Error(`Failed to create directory ${dirPath}: ${e}`),
+    catch: (e) =>
+      new DirectoryCreateError({
+        path: dirPath,
+        message: e instanceof Error ? e.message : String(e),
+        cause: e,
+      }),
   }).pipe(Effect.map(() => undefined))
 
-const readJsonFile = <T>(filePath: string): Effect.Effect<T | null, Error> =>
-  Effect.tryPromise({
-    try: async () => {
-      try {
-        const content = await fs.readFile(filePath, 'utf-8')
-        return JSON.parse(content) as T
-      } catch {
-        return null
-      }
-    },
-    catch: (e) => new Error(`Failed to read ${filePath}: ${e}`),
+const readJsonFile = <T>(
+  filePath: string,
+): Effect.Effect<T | null, FileReadError | IndexCorruptedError> =>
+  Effect.gen(function* () {
+    // Try to read file content
+    const contentResult = yield* Effect.tryPromise({
+      try: () => fs.readFile(filePath, 'utf-8'),
+      catch: (e) => {
+        // File not found is not an error - return null
+        if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT') {
+          return { notFound: true as const }
+        }
+        return new FileReadError({
+          path: filePath,
+          message: e instanceof Error ? e.message : String(e),
+          cause: e,
+        })
+      },
+    }).pipe(
+      Effect.map((content) =>
+        typeof content === 'string' ? { content } : content,
+      ),
+      // Note: catchAll here filters out "file not found" as expected case (returns null),
+      // while other errors are re-thrown to propagate as typed FileReadError
+      Effect.catchAll((e) =>
+        e && 'notFound' in e
+          ? Effect.succeed({ notFound: true as const })
+          : Effect.fail(e),
+      ),
+    )
+
+    // Handle not found
+    if ('notFound' in contentResult) {
+      return null
+    }
+
+    // Parse JSON - corrupted files should fail with IndexCorruptedError
+    return yield* Effect.try({
+      try: () => JSON.parse(contentResult.content) as T,
+      catch: (e) =>
+        new IndexCorruptedError({
+          path: filePath,
+          reason: 'InvalidJson',
+          details: e instanceof Error ? e.message : String(e),
+        }),
+    })
   })
 
 const writeJsonFile = <T>(
   filePath: string,
   data: T,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<void, DirectoryCreateError | FileWriteError> =>
   Effect.gen(function* () {
     const dir = path.dirname(filePath)
     yield* ensureDir(dir)
     yield* Effect.tryPromise({
       try: () => fs.writeFile(filePath, JSON.stringify(data, null, 2)),
-      catch: (e) => new Error(`Failed to write ${filePath}: ${e}`),
+      catch: (e) =>
+        new FileWriteError({
+          path: filePath,
+          message: e instanceof Error ? e.message : String(e),
+          cause: e,
+        }),
     })
   })
 
@@ -75,7 +128,10 @@ export const createStorage = (rootPath: string): IndexStorage => ({
 
 export const initializeIndex = (
   storage: IndexStorage,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<
+  void,
+  DirectoryCreateError | FileReadError | FileWriteError | IndexCorruptedError
+> =>
   Effect.gen(function* () {
     yield* ensureDir(storage.paths.root)
     yield* ensureDir(storage.paths.parsed)
@@ -102,13 +158,13 @@ export const initializeIndex = (
 
 export const loadConfig = (
   storage: IndexStorage,
-): Effect.Effect<IndexConfig | null, Error> =>
+): Effect.Effect<IndexConfig | null, FileReadError | IndexCorruptedError> =>
   readJsonFile<IndexConfig>(storage.paths.config)
 
 export const saveConfig = (
   storage: IndexStorage,
   config: IndexConfig,
-): Effect.Effect<void, Error> =>
+): Effect.Effect<void, DirectoryCreateError | FileWriteError> =>
   writeJsonFile(storage.paths.config, {
     ...config,
     updatedAt: new Date().toISOString(),
@@ -120,13 +176,14 @@ export const saveConfig = (
 
 export const loadDocumentIndex = (
   storage: IndexStorage,
-): Effect.Effect<DocumentIndex | null, Error> =>
+): Effect.Effect<DocumentIndex | null, FileReadError | IndexCorruptedError> =>
   readJsonFile<DocumentIndex>(storage.paths.documents)
 
 export const saveDocumentIndex = (
   storage: IndexStorage,
   index: DocumentIndex,
-): Effect.Effect<void, Error> => writeJsonFile(storage.paths.documents, index)
+): Effect.Effect<void, DirectoryCreateError | FileWriteError> =>
+  writeJsonFile(storage.paths.documents, index)
 
 export const createEmptyDocumentIndex = (rootPath: string): DocumentIndex => ({
   version: INDEX_VERSION,
@@ -140,19 +197,20 @@ export const createEmptyDocumentIndex = (rootPath: string): DocumentIndex => ({
 
 export const loadSectionIndex = (
   storage: IndexStorage,
-): Effect.Effect<SectionIndex | null, Error> =>
+): Effect.Effect<SectionIndex | null, FileReadError | IndexCorruptedError> =>
   readJsonFile<SectionIndex>(storage.paths.sections)
 
 export const saveSectionIndex = (
   storage: IndexStorage,
   index: SectionIndex,
-): Effect.Effect<void, Error> => writeJsonFile(storage.paths.sections, index)
+): Effect.Effect<void, DirectoryCreateError | FileWriteError> =>
+  writeJsonFile(storage.paths.sections, index)
 
 export const createEmptySectionIndex = (): SectionIndex => ({
   version: INDEX_VERSION,
   sections: {},
-  byHeading: {},
-  byDocument: {},
+  byHeading: Object.create(null),
+  byDocument: Object.create(null),
 })
 
 // ============================================================================
@@ -161,18 +219,19 @@ export const createEmptySectionIndex = (): SectionIndex => ({
 
 export const loadLinkIndex = (
   storage: IndexStorage,
-): Effect.Effect<LinkIndex | null, Error> =>
+): Effect.Effect<LinkIndex | null, FileReadError | IndexCorruptedError> =>
   readJsonFile<LinkIndex>(storage.paths.links)
 
 export const saveLinkIndex = (
   storage: IndexStorage,
   index: LinkIndex,
-): Effect.Effect<void, Error> => writeJsonFile(storage.paths.links, index)
+): Effect.Effect<void, DirectoryCreateError | FileWriteError> =>
+  writeJsonFile(storage.paths.links, index)
 
 export const createEmptyLinkIndex = (): LinkIndex => ({
   version: INDEX_VERSION,
-  forward: {},
-  backward: {},
+  forward: Object.create(null),
+  backward: Object.create(null),
   broken: [],
 })
 
@@ -182,7 +241,7 @@ export const createEmptyLinkIndex = (): LinkIndex => ({
 
 export const indexExists = (
   storage: IndexStorage,
-): Effect.Effect<boolean, Error> =>
+): Effect.Effect<boolean, FileReadError> =>
   Effect.tryPromise({
     try: async () => {
       try {
@@ -192,5 +251,10 @@ export const indexExists = (
         return false
       }
     },
-    catch: (e) => new Error(`Failed to check index existence: ${e}`),
+    catch: (e) =>
+      new FileReadError({
+        path: storage.paths.config,
+        message: e instanceof Error ? e.message : String(e),
+        cause: e,
+      }),
   })

package/src/index/types.ts

@@ -75,6 +75,35 @@ export interface LinkIndex {
 // Index Result
 // ============================================================================
 
+/**
+ * Reason why a file was skipped during indexing
+ */
+export type SkipReason =
+  | 'unchanged' // File hash and mtime unchanged
+  | 'excluded' // Matches exclude pattern
+  | 'hidden' // Hidden file or directory
+  | 'not-markdown' // Not a markdown file
+  | 'binary' // Binary file detected
+  | 'oversized' // File too large
+
+/**
+ * Information about a skipped file
+ */
+export interface SkippedFile {
+  readonly path: string
+  readonly reason: SkipReason
+}
+
+/**
+ * Summary of skipped files by reason
+ */
+export interface SkipSummary {
+  readonly unchanged: number
+  readonly excluded: number
+  readonly hidden: number
+  readonly total: number
+}
+
 export interface IndexResult {
   readonly documentsIndexed: number
   readonly sectionsIndexed: number
@@ -83,10 +112,19 @@ export interface IndexResult {
   readonly totalSections: number
   readonly totalLinks: number
   readonly duration: number
-  readonly errors: readonly IndexBuildError[]
+  /** Non-fatal file processing errors (files that couldn't be indexed) */
+  readonly errors: readonly FileProcessingError[]
+  readonly skipped: SkipSummary
 }
 
-export interface IndexBuildError {
+/**
+ * Non-fatal error during file processing in index build.
+ * These are collected and reported but don't stop the build.
+ *
+ * Note: This is distinct from IndexBuildError in errors/index.ts,
+ * which is a TaggedError for fatal build failures.
+ */
+export interface FileProcessingError {
   readonly path: string
   readonly message: string
 }

package/src/index/watcher.ts

@@ -1,14 +1,53 @@
 /**
  * File watcher for automatic re-indexing
+ *
+ * ## Why Not Effect Streams?
+ *
+ * We evaluated using Effect Streams (ALP-101) but decided the current approach is better:
+ *
+ * 1. **chokidar is battle-tested** - Handles OS-specific quirks (FSEvents on macOS,
+ *    inotify on Linux, ReadDirectoryChangesW on Windows)
+ *
+ * 2. **Debouncing handles backpressure** - The 300ms debounce already batches rapid
+ *    changes, so Stream backpressure isn't needed
+ *
+ * 3. **Simple use case** - File change → rebuild index. No complex transformations
+ *    or compositions that would benefit from Stream operators
+ *
+ * 4. **Already Effect-based** - The setup/teardown is wrapped in Effect for proper
+ *    error handling, and we use typed errors (WatchError, IndexBuildError)
+ *
+ * If future requirements need more sophisticated event processing (filtering by
+ * content type, incremental updates, event replay), reconsider Streams then.
  */
 
 import * as path from 'node:path'
 import { watch } from 'chokidar'
 import { Effect } from 'effect'
 
+import {
+  type DirectoryCreateError,
+  type DirectoryWalkError,
+  type FileReadError,
+  type FileWriteError,
+  type IndexCorruptedError,
+  WatchError,
+} from '../errors/index.js'
+import { getChokidarIgnorePatterns } from './ignore-patterns.js'
 import { buildIndex, type IndexOptions } from './indexer.js'
 import { createStorage, indexExists } from './storage.js'
 
+/**
+ * Union of errors that can occur during watch operations
+ */
+export type WatchDirectoryError =
+  | WatchError
+  | DirectoryWalkError
+  | DirectoryCreateError
+  | FileReadError
+  | FileWriteError
+  | IndexCorruptedError
+
 // ============================================================================
 // Watcher Types
 // ============================================================================
@@ -19,7 +58,11 @@ export interface WatcherOptions extends IndexOptions {
     documentsIndexed: number
     duration: number
   }) => void
-  readonly onError?: (error: Error) => void
+  readonly onError?: (error: WatchError) => void
+  /** Whether to honor .gitignore for file watching (default: true) */
+  readonly honorGitignore?: boolean
+  /** Whether to honor .mdcontextignore for file watching (default: true) */
+  readonly honorMdcontextignore?: boolean
 }
 
 export interface Watcher {
@@ -36,7 +79,7 @@ const isMarkdownFile = (filePath: string): boolean =>
 export const watchDirectory = (
   rootPath: string,
   options: WatcherOptions = {},
-): Effect.Effect<Watcher, Error> =>
+): Effect.Effect<Watcher, WatchDirectoryError> =>
   Effect.gen(function* () {
     const resolvedRoot = path.resolve(rootPath)
     const storage = createStorage(resolvedRoot)
@@ -77,18 +120,28 @@ export const watchDirectory = (
           })
         } catch (error) {
           options.onError?.(
-            error instanceof Error ? error : new Error(String(error)),
+            new WatchError({
+              path: resolvedRoot,
+              message:
+                error instanceof Error ? error.message : 'Index rebuild failed',
+              cause: error,
+            }),
           )
         }
       }, debounceMs)
     }
 
-    // Set up chokidar watcher
+    // Build ignore patterns for chokidar
+    const ignorePatterns = yield* getChokidarIgnorePatterns({
+      rootPath: resolvedRoot,
+      cliPatterns: options.exclude,
+      honorGitignore: options.honorGitignore ?? true,
+      honorMdcontextignore: options.honorMdcontextignore ?? true,
+    })
+
+    // Set up chokidar watcher with dynamic ignore patterns
     const watcher = watch(resolvedRoot, {
-      ignored: [
-        /(^|[/\\])\../, // Ignore dotfiles
-        '**/node_modules/**',
-      ],
+      ignored: ignorePatterns,
       persistent: true,
       ignoreInitial: true,
     })
@@ -116,7 +169,12 @@ export const watchDirectory = (
 
     watcher.on('error', (error: unknown) => {
       options.onError?.(
-        error instanceof Error ? error : new Error(String(error)),
+        new WatchError({
+          path: resolvedRoot,
+          message:
+            error instanceof Error ? error.message : 'File watcher error',
+          cause: error,
+        }),
       )
     })
 

package/src/index.ts

@@ -2,7 +2,29 @@
  * mdcontext - Token-efficient markdown analysis for LLMs
  */
 
+// Config utilities for user config files
+export type { PartialMdContextConfig } from './config/service.js'
 export * from './core/index.js'
 export * from './index/index.js'
 export * from './parser/index.js'
 export * from './utils/index.js'
+
+/**
+ * Type-safe configuration helper for mdcontext.config.ts files.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from 'mdcontext'
+ *
+ * export default defineConfig({
+ *   index: {
+ *     maxDepth: 5,
+ *   },
+ * })
+ * ```
+ */
+export const defineConfig = <
+  T extends import('./config/service.js').PartialMdContextConfig,
+>(
+  config: T,
+): T => config