mdcontext 0.0.1 → 0.2.0

package/src/cli/typo-suggester.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for typo-suggester
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { CommandSchema } from './flag-schemas.js'
+import {
+  formatValidFlags,
+  levenshteinDistance,
+  suggestFlag,
+} from './typo-suggester.js'
+
+describe('levenshteinDistance', () => {
+  it('returns 0 for identical strings', () => {
+    expect(levenshteinDistance('test', 'test')).toBe(0)
+  })
+
+  it('returns string length for empty comparison', () => {
+    expect(levenshteinDistance('test', '')).toBe(4)
+    expect(levenshteinDistance('', 'test')).toBe(4)
+  })
+
+  it('calculates single character difference', () => {
+    expect(levenshteinDistance('test', 'tset')).toBe(2) // transposition
+    expect(levenshteinDistance('test', 'tests')).toBe(1) // insertion
+    expect(levenshteinDistance('test', 'tes')).toBe(1) // deletion
+    expect(levenshteinDistance('test', 'tast')).toBe(1) // substitution
+  })
+
+  it('calculates distance for common typos', () => {
+    expect(levenshteinDistance('json', 'jsno')).toBe(2)
+    expect(levenshteinDistance('limit', 'limt')).toBe(1)
+    expect(levenshteinDistance('tokens', 'toekns')).toBe(2)
+  })
+})
+
+describe('suggestFlag', () => {
+  const mockSchema: CommandSchema = {
+    name: 'test',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output JSON' },
+      { name: 'limit', type: 'string', alias: 'n', description: 'Max results' },
+      { name: 'threshold', type: 'string', description: 'Threshold' },
+    ],
+  }
+
+  it('suggests correct flag for typo', () => {
+    const result = suggestFlag('--jsno', mockSchema)
+    expect(result).toBeDefined()
+    expect(result?.flag).toBe('--json')
+  })
+
+  it('suggests correct flag for missing letter', () => {
+    const result = suggestFlag('--limt', mockSchema)
+    expect(result).toBeDefined()
+    expect(result?.flag).toBe('--limit')
+  })
+
+  it('returns undefined for no close match', () => {
+    const result = suggestFlag('--foobar', mockSchema)
+    expect(result).toBeUndefined()
+  })
+
+  it('handles prefix matches', () => {
+    const result = suggestFlag('--js', mockSchema)
+    expect(result).toBeDefined()
+    expect(result?.flag).toBe('--json')
+  })
+
+  it('handles short flag typos', () => {
+    const result = suggestFlag('-m', mockSchema)
+    expect(result).toBeDefined()
+    expect(result?.flag).toBe('--limit') // -m is close to -n
+  })
+
+  it('respects maxDistance parameter', () => {
+    const result = suggestFlag('--jsno', mockSchema, 1)
+    expect(result).toBeUndefined() // distance is 2, exceeds max
+  })
+})
+
+describe('formatValidFlags', () => {
+  const mockSchema: CommandSchema = {
+    name: 'test',
+    flags: [
+      { name: 'json', type: 'boolean', description: 'Output JSON' },
+      { name: 'limit', type: 'string', alias: 'n', description: 'Max results' },
+      { name: 'threshold', type: 'string' },
+    ],
+  }
+
+  it('formats flags with descriptions', () => {
+    const output = formatValidFlags(mockSchema)
+    expect(output).toContain('--json')
+    expect(output).toContain('Output JSON')
+    expect(output).toContain('--limit, -n')
+    expect(output).toContain('Max results')
+    expect(output).toContain('--threshold')
+  })
+
+  it('includes alias when present', () => {
+    const output = formatValidFlags(mockSchema)
+    expect(output).toContain(', -n')
+  })
+})

package/src/cli/typo-suggester.ts

@@ -0,0 +1,130 @@
+/**
+ * Typo Suggester
+ *
+ * Uses Levenshtein distance to suggest correct flags when users mistype.
+ */
+
+import type { CommandSchema } from './flag-schemas.js'
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export const levenshteinDistance = (a: string, b: string): number => {
+  const matrix: number[][] = []
+
+  // Initialize first column
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i]
+  }
+
+  // Initialize first row
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0]![j] = j
+  }
+
+  // Fill in the rest
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      matrix[i]![j] = Math.min(
+        matrix[i - 1]![j]! + 1, // deletion
+        matrix[i]![j - 1]! + 1, // insertion
+        matrix[i - 1]![j - 1]! + cost, // substitution
+      )
+    }
+  }
+
+  return matrix[a.length]![b.length]!
+}
+
+/**
+ * Suggestion result
+ */
+export interface Suggestion {
+  flag: string
+  distance: number
+  description: string | undefined
+}
+
+/**
+ * Find the best flag suggestion for a typo
+ *
+ * @param typo - The mistyped flag (e.g., '--jsno')
+ * @param schema - The command schema to search
+ * @param maxDistance - Maximum Levenshtein distance to consider (default: 2)
+ * @returns Best matching flag or undefined
+ */
+export const suggestFlag = (
+  typo: string,
+  schema: CommandSchema,
+  maxDistance: number = 2,
+): Suggestion | undefined => {
+  // Normalize the typo (remove leading dashes for comparison)
+  const normalizedTypo = typo.replace(/^-+/, '')
+
+  let bestMatch: Suggestion | undefined
+  let bestDistance = Infinity
+
+  for (const spec of schema.flags) {
+    // Check against full flag name
+    const flagName = spec.name
+    const distance = levenshteinDistance(normalizedTypo, flagName)
+
+    if (distance <= maxDistance && distance < bestDistance) {
+      bestDistance = distance
+      bestMatch = {
+        flag: `--${spec.name}`,
+        distance,
+        description: spec.description,
+      }
+    }
+
+    // Also check against alias if present
+    if (spec.alias) {
+      const aliasDistance = levenshteinDistance(normalizedTypo, spec.alias)
+      if (aliasDistance <= maxDistance && aliasDistance < bestDistance) {
+        bestDistance = aliasDistance
+        bestMatch = {
+          flag: `--${spec.name}`,
+          distance: aliasDistance,
+          description: spec.description,
+        }
+      }
+    }
+  }
+
+  // Prefer exact prefix matches (e.g., '--js' should suggest '--json')
+  if (!bestMatch || bestDistance > 0) {
+    for (const spec of schema.flags) {
+      if (spec.name.startsWith(normalizedTypo)) {
+        // Prefix match - this is likely what they meant
+        const prefixDistance = spec.name.length - normalizedTypo.length
+        if (prefixDistance <= maxDistance && prefixDistance < bestDistance) {
+          bestDistance = prefixDistance
+          bestMatch = {
+            flag: `--${spec.name}`,
+            distance: prefixDistance,
+            description: spec.description,
+          }
+        }
+      }
+    }
+  }
+
+  return bestMatch
+}
+
+/**
+ * Format a list of valid flags for a command
+ */
+export const formatValidFlags = (schema: CommandSchema): string => {
+  const lines: string[] = []
+
+  for (const spec of schema.flags) {
+    const alias = spec.alias ? `, -${spec.alias}` : ''
+    const desc = spec.description ? `  ${spec.description}` : ''
+    lines.push(`  --${spec.name}${alias}${desc}`)
+  }
+
+  return lines.join('\n')
+}

package/src/cli/utils.ts

@@ -0,0 +1,259 @@
+/**
+ * CLI Utility Functions
+ *
+ * Shared helper functions used across CLI commands.
+ */
+
+import * as fsPromises from 'node:fs/promises'
+import * as path from 'node:path'
+import { Effect } from 'effect'
+import { listNamespaces } from '../embeddings/embedding-namespace.js'
+import { DirectoryWalkError } from '../errors/index.js'
+
+/**
+ * Format object as JSON string
+ */
+export const formatJson = (obj: unknown, pretty: boolean): string => {
+  return pretty ? JSON.stringify(obj, null, 2) : JSON.stringify(obj)
+}
+
+/**
+ * Check if filename is a markdown file
+ */
+export const isMarkdownFile = (filename: string): boolean => {
+  return filename.endsWith('.md') || filename.endsWith('.mdx')
+}
+
+/**
+ * Recursively walk directory and collect markdown files (async version).
+ * @deprecated Use walkDirEffect for typed error handling
+ */
+export const walkDir = async (dir: string): Promise<string[]> => {
+  const files: string[] = []
+  const entries = await fsPromises.readdir(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+
+    // Skip hidden directories and node_modules
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+      continue
+    }
+
+    if (entry.isDirectory()) {
+      const subFiles = await walkDir(fullPath)
+      files.push(...subFiles)
+    } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+      files.push(fullPath)
+    }
+  }
+
+  return files
+}
+
+/**
+ * Recursively walk directory and collect markdown files.
+ *
+ * @param dir - Directory to walk
+ * @returns List of markdown file paths
+ *
+ * @throws DirectoryWalkError - Cannot read or traverse directory
+ */
+export const walkDirEffect = (
+  dir: string,
+): Effect.Effect<readonly string[], DirectoryWalkError> =>
+  Effect.gen(function* () {
+    const files: string[] = []
+
+    const entries = yield* Effect.tryPromise({
+      try: () => fsPromises.readdir(dir, { withFileTypes: true }),
+      catch: (e) =>
+        new DirectoryWalkError({
+          path: dir,
+          message: `Cannot read directory: ${e instanceof Error ? e.message : String(e)}`,
+          cause: e,
+        }),
+    })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      // Skip hidden directories and node_modules
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+        continue
+      }
+
+      if (entry.isDirectory()) {
+        const subFiles = yield* walkDirEffect(fullPath)
+        files.push(...subFiles)
+      } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+        files.push(fullPath)
+      }
+    }
+
+    return files
+  })
+
+/**
+ * Check if a query looks like a regex pattern
+ */
+export const isRegexPattern = (query: string): boolean => {
+  // Has regex special characters (excluding simple spaces and common punctuation)
+  return /[.*+?^${}()|[\]\\]/.test(query)
+}
+
+/**
+ * Check if embeddings exist for a directory.
+ * Checks for namespaced embeddings in .mdcontext/embeddings/<namespace>/vectors.bin
+ */
+export const hasEmbeddings = async (dir: string): Promise<boolean> => {
+  try {
+    const namespaces = await Effect.runPromise(
+      listNamespaces(dir).pipe(Effect.catchAll(() => Effect.succeed([]))),
+    )
+    return namespaces.length > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Find the nearest parent directory containing an mdcontext index.
+ * Searches from the specified directory up to the filesystem root.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns The directory containing the index, or null if not found
+ */
+export const findIndexRoot = async (
+  startDir: string,
+): Promise<string | null> => {
+  let currentDir = path.resolve(startDir)
+  const root = path.parse(currentDir).root
+
+  while (currentDir !== root) {
+    const sectionsPath = path.join(
+      currentDir,
+      '.mdcontext',
+      'indexes',
+      'sections.json',
+    )
+    try {
+      await fsPromises.access(sectionsPath)
+      return currentDir // Found an index
+    } catch {
+      // No index here, try parent
+      const parent = path.dirname(currentDir)
+      if (parent === currentDir) break // Reached root
+      currentDir = parent
+    }
+  }
+
+  // Also check root
+  const rootSectionsPath = path.join(
+    root,
+    '.mdcontext',
+    'indexes',
+    'sections.json',
+  )
+  try {
+    await fsPromises.access(rootSectionsPath)
+    return root
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Get index information for display
+ */
+export interface IndexInfo {
+  exists: boolean
+  lastUpdated?: string | undefined
+  sectionCount?: number | undefined
+  embeddingsExist: boolean
+  vectorCount?: number | undefined
+  /** The actual directory where the index was found (may differ from requested dir) */
+  indexRoot?: string | undefined
+}
+
+export const getIndexInfo = async (dir: string): Promise<IndexInfo> => {
+  // First try the specified directory
+  let indexRoot = dir
+  let sectionsPath = path.join(dir, '.mdcontext', 'indexes', 'sections.json')
+
+  let exists = false
+  let lastUpdated: string | undefined
+  let sectionCount: number | undefined
+  let embeddingsExist = false
+  let vectorCount: number | undefined
+
+  // Check sections index in specified directory
+  try {
+    const stat = await fsPromises.stat(sectionsPath)
+    exists = true
+    lastUpdated = stat.mtime.toISOString()
+
+    const content = await fsPromises.readFile(sectionsPath, 'utf-8')
+    const sections = JSON.parse(content)
+    sectionCount = Object.keys(sections.sections || {}).length
+  } catch {
+    // Index doesn't exist in specified directory, try to find in parent directories
+    const foundRoot = await findIndexRoot(dir)
+    if (foundRoot) {
+      indexRoot = foundRoot
+      sectionsPath = path.join(
+        foundRoot,
+        '.mdcontext',
+        'indexes',
+        'sections.json',
+      )
+
+      try {
+        const stat = await fsPromises.stat(sectionsPath)
+        exists = true
+        lastUpdated = stat.mtime.toISOString()
+
+        const content = await fsPromises.readFile(sectionsPath, 'utf-8')
+        const sections = JSON.parse(content)
+        sectionCount = Object.keys(sections.sections || {}).length
+      } catch {
+        // Still failed
+      }
+    }
+  }
+
+  // Check namespaced embeddings
+  try {
+    const namespaces = await Effect.runPromise(
+      listNamespaces(indexRoot).pipe(Effect.catchAll(() => Effect.succeed([]))),
+    )
+
+    if (namespaces.length > 0) {
+      embeddingsExist = true
+      // Find active namespace or use first one
+      const activeNs = namespaces.find((ns) => ns.isActive) ?? namespaces[0]
+      if (activeNs) {
+        vectorCount = activeNs.vectorCount
+        // Use namespace's updatedAt if more recent
+        if (activeNs.updatedAt) {
+          const nsDate = new Date(activeNs.updatedAt)
+          const currentDate = lastUpdated ? new Date(lastUpdated) : new Date(0)
+          if (nsDate > currentDate) {
+            lastUpdated = activeNs.updatedAt
+          }
+        }
+      }
+    }
+  } catch {
+    // Embeddings don't exist
+  }
+
+  return {
+    exists,
+    lastUpdated,
+    sectionCount,
+    embeddingsExist,
+    vectorCount,
+    indexRoot: exists && indexRoot !== dir ? indexRoot : undefined,
+  }
+}