mdcontext 0.0.1 → 0.2.0

package/src/config/testing.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Testing Utilities Unit Tests
+ *
+ * Tests for the config testing utilities that make it easy to test
+ * code that depends on ConfigService.
+ */
+
+import { Effect } from 'effect'
+import { describe, expect, it } from 'vitest'
+import { defaultConfig } from './schema.js'
+import { ConfigService } from './service.js'
+import {
+  runWithConfig,
+  runWithConfigSync,
+  TestConfigLayer,
+  withTestConfig,
+} from './testing.js'
+
+describe('Testing Utilities', () => {
+  describe('TestConfigLayer', () => {
+    it('should provide default configuration values', async () => {
+      const program = Effect.gen(function* () {
+        return yield* ConfigService
+      })
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(TestConfigLayer)),
+      )
+
+      expect(result).toEqual(defaultConfig)
+    })
+
+    it('should be suitable for most tests', async () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(TestConfigLayer)),
+      )
+
+      expect(result).toBe(10)
+    })
+  })
+
+  describe('withTestConfig', () => {
+    it('should override specific values', async () => {
+      const layer = withTestConfig({
+        index: { maxDepth: 5 },
+      })
+
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      )
+
+      expect(result).toBe(5)
+    })
+
+    it('should preserve defaults for unspecified values', async () => {
+      const layer = withTestConfig({
+        index: { maxDepth: 5 },
+      })
+
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return {
+          maxDepth: config.index.maxDepth,
+          excludePatterns: config.index.excludePatterns,
+          defaultLimit: config.search.defaultLimit,
+        }
+      })
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      )
+
+      expect(result.maxDepth).toBe(5)
+      expect(result.excludePatterns).toEqual([
+        'node_modules',
+        '.git',
+        'dist',
+        'build',
+      ])
+      expect(result.defaultLimit).toBe(10)
+    })
+
+    it('should allow overriding multiple sections', async () => {
+      const layer = withTestConfig({
+        index: { maxDepth: 5 },
+        output: { debug: true, verbose: true },
+        search: { defaultLimit: 20 },
+      })
+
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return {
+          maxDepth: config.index.maxDepth,
+          debug: config.output.debug,
+          verbose: config.output.verbose,
+          defaultLimit: config.search.defaultLimit,
+        }
+      })
+
+      const result = await Effect.runPromise(
+        program.pipe(Effect.provide(layer)),
+      )
+
+      expect(result.maxDepth).toBe(5)
+      expect(result.debug).toBe(true)
+      expect(result.verbose).toBe(true)
+      expect(result.defaultLimit).toBe(20)
+    })
+  })
+
+  describe('runWithConfig', () => {
+    it('should run effect with default config when no overrides provided', async () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = await runWithConfig(program)
+
+      expect(result).toBe(10)
+    })
+
+    it('should run effect with custom config overrides', async () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = await runWithConfig(program, { index: { maxDepth: 5 } })
+
+      expect(result).toBe(5)
+    })
+
+    it('should work with complex effects', async () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth > 5 ? 'deep' : 'shallow'
+      })
+
+      const deepResult = await runWithConfig(program, {
+        index: { maxDepth: 10 },
+      })
+      const shallowResult = await runWithConfig(program, {
+        index: { maxDepth: 3 },
+      })
+
+      expect(deepResult).toBe('deep')
+      expect(shallowResult).toBe('shallow')
+    })
+  })
+
+  describe('runWithConfigSync', () => {
+    it('should run effect synchronously with default config', () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = runWithConfigSync(program)
+
+      expect(result).toBe(10)
+    })
+
+    it('should run effect synchronously with custom config', () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.index.maxDepth
+      })
+
+      const result = runWithConfigSync(program, { index: { maxDepth: 5 } })
+
+      expect(result).toBe(5)
+    })
+
+    it('should work with pure computations', () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        const depth = config.index.maxDepth
+        const limit = config.search.defaultLimit
+        return depth * limit
+      })
+
+      const result = runWithConfigSync(program, {
+        index: { maxDepth: 5 },
+        search: { defaultLimit: 20 },
+      })
+
+      expect(result).toBe(100)
+    })
+  })
+
+  describe('real-world usage patterns', () => {
+    it('should enable testing services that depend on config', async () => {
+      const indexService = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return {
+          shouldIndex: (depth: number) => depth <= config.index.maxDepth,
+          patterns: config.index.excludePatterns,
+        }
+      })
+
+      const testLayer = withTestConfig({ index: { maxDepth: 3 } })
+
+      const service = await Effect.runPromise(
+        indexService.pipe(Effect.provide(testLayer)),
+      )
+
+      expect(service.shouldIndex(2)).toBe(true)
+      expect(service.shouldIndex(3)).toBe(true)
+      expect(service.shouldIndex(4)).toBe(false)
+    })
+
+    it('should support parameterized tests', async () => {
+      const program = Effect.gen(function* () {
+        const config = yield* ConfigService
+        return config.output.format
+      })
+
+      const textResult = await runWithConfig(program, {
+        output: { format: 'text' },
+      })
+      const jsonResult = await runWithConfig(program, {
+        output: { format: 'json' },
+      })
+
+      expect(textResult).toBe('text')
+      expect(jsonResult).toBe('json')
+    })
+
+    it('should allow testing error conditions', async () => {
+      const validateConfig = Effect.gen(function* () {
+        const config = yield* ConfigService
+        if (
+          config.search.minSimilarity < 0 ||
+          config.search.minSimilarity > 1
+        ) {
+          return yield* Effect.fail('Invalid similarity range')
+        }
+        return config.search.minSimilarity
+      })
+
+      const validResult = await runWithConfig(validateConfig, {
+        search: { minSimilarity: 0.5 },
+      })
+      expect(validResult).toBe(0.5)
+
+      const invalidLayer = withTestConfig({ search: { minSimilarity: 1.5 } })
+      const invalidProgram = validateConfig.pipe(Effect.provide(invalidLayer))
+      const invalidResult = await Effect.runPromiseExit(invalidProgram)
+
+      expect(invalidResult._tag).toBe('Failure')
+    })
+  })
+})

package/src/config/testing.ts

@@ -0,0 +1,110 @@
+/**
+ * Configuration Testing Utilities
+ *
+ * Provides helpers for testing code that depends on ConfigService.
+ * Use these utilities to create isolated test environments without
+ * environment pollution.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { TestConfigLayer, withTestConfig } from './config/testing.js'
+ *
+ * // Use default test config
+ * const result = await Effect.runPromise(
+ *   myProgram.pipe(Effect.provide(TestConfigLayer))
+ * )
+ *
+ * // Override specific values
+ * const result = await Effect.runPromise(
+ *   myProgram.pipe(Effect.provide(withTestConfig({
+ *     index: { maxDepth: 5 }
+ *   })))
+ * )
+ * ```
+ */
+
+import { Effect, Layer } from 'effect'
+import { defaultConfig } from './schema.js'
+import {
+  ConfigService,
+  makeConfigLayerPartial,
+  type PartialMdContextConfig,
+} from './service.js'
+
+/**
+ * Default test configuration layer.
+ * Uses all default values - suitable for most tests.
+ */
+export const TestConfigLayer: Layer.Layer<ConfigService> = Layer.succeed(
+  ConfigService,
+  defaultConfig,
+)
+
+/**
+ * Create a test config layer with specific overrides.
+ *
+ * @param overrides - Partial config to merge with defaults
+ * @returns Layer providing ConfigService with merged config
+ *
+ * @example
+ * const layer = withTestConfig({
+ *   index: { maxDepth: 5 },
+ *   output: { debug: true }
+ * })
+ */
+export const withTestConfig = (
+  overrides: PartialMdContextConfig,
+): Layer.Layer<ConfigService> => makeConfigLayerPartial(overrides)
+
+/**
+ * Run an Effect with a specific configuration.
+ *
+ * Convenience function that provides the config layer and runs the effect.
+ *
+ * @param effect - The Effect to run
+ * @param config - Optional partial config overrides
+ * @returns Promise with the effect result
+ *
+ * @example
+ * const result = await runWithConfig(
+ *   Effect.gen(function* () {
+ *     const config = yield* ConfigService
+ *     return config.index.maxDepth
+ *   }),
+ *   { index: { maxDepth: 5 } }
+ * )
+ * // result === 5
+ */
+export const runWithConfig = <A, E>(
+  effect: Effect.Effect<A, E, ConfigService>,
+  config?: PartialMdContextConfig,
+): Promise<A> => {
+  const layer = config ? withTestConfig(config) : TestConfigLayer
+  return Effect.runPromise(effect.pipe(Effect.provide(layer)))
+}
+
+/**
+ * Run an Effect with a specific configuration synchronously.
+ *
+ * @param effect - The Effect to run
+ * @param config - Optional partial config overrides
+ * @returns The effect result
+ *
+ * @example
+ * const result = runWithConfigSync(
+ *   Effect.gen(function* () {
+ *     const config = yield* ConfigService
+ *     return config.index.maxDepth
+ *   }),
+ *   { index: { maxDepth: 5 } }
+ * )
+ * // result === 5
+ */
+export const runWithConfigSync = <A, E>(
+  effect: Effect.Effect<A, E, ConfigService>,
+  config?: PartialMdContextConfig,
+): A => {
+  const layer = config ? withTestConfig(config) : TestConfigLayer
+  return Effect.runSync(effect.pipe(Effect.provide(layer)))
+}

package/src/core/index.ts

@@ -0,0 +1 @@
+export * from './types.js'

package/src/core/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Core data types for mdcontext
+ * Based on DESIGN.md specifications
+ */
+
+// ============================================================================
+// Document Types
+// ============================================================================
+
+export interface MdDocument {
+  readonly id: string
+  readonly path: string
+  readonly title: string
+  readonly frontmatter: Record<string, unknown>
+  readonly sections: readonly MdSection[]
+  readonly links: readonly MdLink[]
+  readonly codeBlocks: readonly MdCodeBlock[]
+  readonly metadata: DocumentMetadata
+}
+
+export interface DocumentMetadata {
+  readonly wordCount: number
+  readonly tokenCount: number
+  readonly headingCount: number
+  readonly linkCount: number
+  readonly codeBlockCount: number
+  readonly lastModified: Date
+  readonly indexedAt: Date
+}
+
+// ============================================================================
+// Section Types
+// ============================================================================
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
+
+export interface MdSection {
+  readonly id: string
+  readonly heading: string
+  readonly level: HeadingLevel
+  readonly content: string
+  readonly plainText: string
+  readonly startLine: number
+  readonly endLine: number
+  readonly children: readonly MdSection[]
+  readonly metadata: SectionMetadata
+}
+
+export interface SectionMetadata {
+  readonly wordCount: number
+  readonly tokenCount: number
+  readonly hasCode: boolean
+  readonly hasList: boolean
+  readonly hasTable: boolean
+}
+
+// ============================================================================
+// Link Types
+// ============================================================================
+
+export type LinkType = 'internal' | 'external' | 'image'
+
+export interface MdLink {
+  readonly type: LinkType
+  readonly href: string
+  readonly text: string
+  readonly sectionId: string
+  readonly line: number
+}
+
+// ============================================================================
+// Code Block Types
+// ============================================================================
+
+export interface MdCodeBlock {
+  readonly language: string | null
+  readonly content: string
+  readonly sectionId: string
+  readonly startLine: number
+  readonly endLine: number
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Parse error from markdown parsing
+ *
+ * Note: This interface is used by parser.ts. For the TaggedError version
+ * that works with Effect's error handling, see src/errors/index.ts ParseError.
+ */
+export interface ParseError {
+  readonly _tag: 'ParseError'
+  readonly message: string
+  readonly line?: number | undefined
+  readonly column?: number | undefined
+}
+
+// ============================================================================
+// Constructor Functions
+// ============================================================================
+
+export const ParseError = (
+  message: string,
+  line?: number,
+  column?: number,
+): ParseError => ({
+  _tag: 'ParseError',
+  message,
+  line,
+  column,
+})

package/src/duplicates/detector.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tests for duplicate content detection
+ */
+
+import { describe, expect, it } from 'vitest'
+import {
+  collapseDuplicates,
+  type DuplicateGroup,
+  type DuplicateSectionInfo,
+} from './detector.js'
+
+// ============================================================================
+// Test Data
+// ============================================================================
+
+const makeSectionInfo = (
+  id: string,
+  path: string,
+  heading: string,
+): DuplicateSectionInfo => ({
+  sectionId: id,
+  documentPath: path,
+  heading,
+  startLine: 1,
+  endLine: 10,
+  tokenCount: 100,
+})
+
+const makeGroup = (
+  primary: DuplicateSectionInfo,
+  duplicates: DuplicateSectionInfo[],
+): DuplicateGroup => ({
+  primary,
+  duplicates,
+  method: 'exact',
+  similarity: 1.0,
+})
+
+// ============================================================================
+// collapseDuplicates Tests
+// ============================================================================
+
+describe('collapseDuplicates', () => {
+  it('returns all results when no duplicate groups', () => {
+    const results = [
+      { sectionId: 'a', documentPath: 'doc1.md', score: 0.9 },
+      { sectionId: 'b', documentPath: 'doc2.md', score: 0.8 },
+      { sectionId: 'c', documentPath: 'doc3.md', score: 0.7 },
+    ]
+    const groups: DuplicateGroup[] = []
+
+    const collapsed = collapseDuplicates(results, groups)
+
+    expect(collapsed.length).toBe(3)
+    expect(collapsed[0]?.result.sectionId).toBe('a')
+    expect(collapsed[0]?.duplicateCount).toBe(0)
+    expect(collapsed[1]?.result.sectionId).toBe('b')
+    expect(collapsed[2]?.result.sectionId).toBe('c')
+  })
+
+  it('collapses duplicates and keeps primary', () => {
+    const section1 = makeSectionInfo('a', 'doc1.md', 'Section A')
+    const section2 = makeSectionInfo('b', 'doc2.md', 'Section A (copy)')
+
+    const results = [
+      { sectionId: 'a', documentPath: 'doc1.md', score: 0.9 },
+      { sectionId: 'b', documentPath: 'doc2.md', score: 0.8 },
+    ]
+    const groups = [makeGroup(section1, [section2])]
+
+    const collapsed = collapseDuplicates(results, groups)
+
+    expect(collapsed.length).toBe(1)
+    expect(collapsed[0]?.result.sectionId).toBe('a')
+    expect(collapsed[0]?.duplicateCount).toBe(1)
+  })
+
+  it('collapses when duplicate appears first', () => {
+    const section1 = makeSectionInfo('a', 'doc1.md', 'Section A')
+    const section2 = makeSectionInfo('b', 'doc2.md', 'Section A (copy)')
+
+    // Duplicate appears first in results
+    const results = [
+      { sectionId: 'b', documentPath: 'doc2.md', score: 0.9 },
+      { sectionId: 'a', documentPath: 'doc1.md', score: 0.8 },
+    ]
+    const groups = [makeGroup(section1, [section2])]
+
+    const collapsed = collapseDuplicates(results, groups)
+
+    // Should keep the first result (b), not the primary (a)
+    expect(collapsed.length).toBe(1)
+    expect(collapsed[0]?.result.sectionId).toBe('b')
+    expect(collapsed[0]?.duplicateCount).toBe(1)
+  })
+
+  it('includes duplicate locations when showLocations is true', () => {
+    const section1 = makeSectionInfo('a', 'doc1.md', 'Section A')
+    const section2 = makeSectionInfo('b', 'doc2.md', 'Section A (copy)')
+    const section3 = makeSectionInfo('c', 'doc3.md', 'Section A (copy 2)')
+
+    const results = [{ sectionId: 'a', documentPath: 'doc1.md', score: 0.9 }]
+    const groups = [makeGroup(section1, [section2, section3])]
+
+    const collapsed = collapseDuplicates(results, groups, {
+      showLocations: true,
+    })
+
+    expect(collapsed.length).toBe(1)
+    expect(collapsed[0]?.duplicateCount).toBe(2)
+    expect(collapsed[0]?.duplicateLocations).toBeDefined()
+    expect(collapsed[0]?.duplicateLocations?.length).toBe(2)
+    expect(collapsed[0]?.duplicateLocations?.[0]?.documentPath).toBe('doc2.md')
+    expect(collapsed[0]?.duplicateLocations?.[1]?.documentPath).toBe('doc3.md')
+  })
+
+  it('respects maxLocations option', () => {
+    const section1 = makeSectionInfo('a', 'doc1.md', 'Section A')
+    const section2 = makeSectionInfo('b', 'doc2.md', 'Copy 1')
+    const section3 = makeSectionInfo('c', 'doc3.md', 'Copy 2')
+    const section4 = makeSectionInfo('d', 'doc4.md', 'Copy 3')
+    const section5 = makeSectionInfo('e', 'doc5.md', 'Copy 4')
+
+    const results = [{ sectionId: 'a', documentPath: 'doc1.md', score: 0.9 }]
+    const groups = [
+      makeGroup(section1, [section2, section3, section4, section5]),
+    ]
+
+    const collapsed = collapseDuplicates(results, groups, {
+      showLocations: true,
+      maxLocations: 2,
+    })
+
+    expect(collapsed[0]?.duplicateCount).toBe(4)
+    expect(collapsed[0]?.duplicateLocations?.length).toBe(2)
+  })
+
+  it('handles multiple duplicate groups', () => {
+    const sectionA1 = makeSectionInfo('a1', 'doc1.md', 'Section A')
+    const sectionA2 = makeSectionInfo('a2', 'doc2.md', 'Section A copy')
+    const sectionB1 = makeSectionInfo('b1', 'doc3.md', 'Section B')
+    const sectionB2 = makeSectionInfo('b2', 'doc4.md', 'Section B copy')
+
+    const results = [
+      { sectionId: 'a1', documentPath: 'doc1.md', score: 0.9 },
+      { sectionId: 'b1', documentPath: 'doc3.md', score: 0.8 },
+      { sectionId: 'a2', documentPath: 'doc2.md', score: 0.7 },
+      { sectionId: 'b2', documentPath: 'doc4.md', score: 0.6 },
+    ]
+    const groups = [
+      makeGroup(sectionA1, [sectionA2]),
+      makeGroup(sectionB1, [sectionB2]),
+    ]
+
+    const collapsed = collapseDuplicates(results, groups)
+
+    expect(collapsed.length).toBe(2)
+    expect(collapsed[0]?.result.sectionId).toBe('a1')
+    expect(collapsed[0]?.duplicateCount).toBe(1)
+    expect(collapsed[1]?.result.sectionId).toBe('b1')
+    expect(collapsed[1]?.duplicateCount).toBe(1)
+  })
+
+  it('handles empty results', () => {
+    const collapsed = collapseDuplicates([], [])
+    expect(collapsed.length).toBe(0)
+  })
+
+  it('does not include locations when showLocations is false', () => {
+    const section1 = makeSectionInfo('a', 'doc1.md', 'Section A')
+    const section2 = makeSectionInfo('b', 'doc2.md', 'Section A copy')
+
+    const results = [{ sectionId: 'a', documentPath: 'doc1.md', score: 0.9 }]
+    const groups = [makeGroup(section1, [section2])]
+
+    const collapsed = collapseDuplicates(results, groups, {
+      showLocations: false,
+    })
+
+    expect(collapsed[0]?.duplicateCount).toBe(1)
+    expect(collapsed[0]?.duplicateLocations).toBeUndefined()
+  })
+})