incur 0.4.0 → 0.4.2

package/src/internal/dereference.ts

@@ -0,0 +1,75 @@
+/**
+ * Dereferences all local `$ref` pointers in a JSON object (e.g. `{"$ref": "#/components/schemas/User"}`),
+ * replacing them inline with the resolved values. Only handles local (`#/...`) references.
+ *
+ * Handles circular references by caching a mutable placeholder before recursing.
+ *
+ * Minimal reimplementation of the dereferencing behavior from `@apidevtools/json-schema-ref-parser`
+ * (https://github.com/APIDevTools/json-schema-ref-parser). Only supports in-memory, local-pointer
+ * resolution — no file/URL resolution, no `$id` scoping.
+ */
+export function dereference<value>(root: value): value {
+  const cache = new Map<string, unknown>()
+  return walk(root, root, cache) as value
+}
+
+function walk(node: unknown, root: unknown, cache: Map<string, unknown>): unknown {
+  if (Array.isArray(node)) return node.map((item) => walk(item, root, cache))
+
+  if (typeof node !== 'object' || node === null) return node
+
+  const obj = node as Record<string, unknown>
+
+  // Resolve $ref pointer
+  if (typeof obj.$ref === 'string' && obj.$ref.startsWith('#')) {
+    const ref = obj.$ref
+    if (cache.has(ref)) return cache.get(ref)
+
+    const resolved = resolvePointer(root, ref)
+
+    // Non-object targets (primitives, arrays) can't be circular — resolve directly
+    if (typeof resolved !== 'object' || resolved === null || Array.isArray(resolved)) {
+      const dereferenced = walk(resolved, root, cache)
+      cache.set(ref, dereferenced)
+      return dereferenced
+    }
+
+    // Use a mutable placeholder so circular refs resolve to the same object.
+    // If the walked result is not a plain object (e.g. chained ref to primitive/array),
+    // skip the placeholder and cache directly.
+    const placeholder: Record<string, unknown> = {}
+    cache.set(ref, placeholder)
+    const dereferenced = walk(resolved, root, cache)
+    if (typeof dereferenced !== 'object' || dereferenced === null || Array.isArray(dereferenced)) {
+      cache.set(ref, dereferenced)
+      return dereferenced
+    }
+    Object.assign(placeholder, dereferenced)
+    return placeholder
+  }
+
+  const result: Record<string, unknown> = {}
+  for (const key of Object.keys(obj)) result[key] = walk(obj[key], root, cache)
+  return result
+}
+
+/** Resolves a JSON Pointer (e.g. `#/components/schemas/User`) against a root object. */
+function resolvePointer(root: unknown, pointer: string): unknown {
+  // "#" or "#/" → root
+  const fragment = pointer.slice(1)
+  if (fragment === '' || fragment === '/') return root
+
+  const parts = fragment
+    .slice(1)
+    .split('/')
+    .map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'))
+
+  let current: unknown = root
+  for (const part of parts) {
+    if (typeof current !== 'object' || current === null)
+      throw new Error(`Cannot resolve $ref "${pointer}": path segment "${part}" not found`)
+    current = (current as Record<string, unknown>)[part]
+    if (current === undefined) throw new Error(`Cannot resolve $ref "${pointer}": "${part}" not found`)
+  }
+  return current
+}

package/src/internal/helpers.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'vitest'
+
+import { levenshtein, suggest } from './helpers.js'
+
+describe('levenshtein', () => {
+  test('identical strings', () => {
+    expect(levenshtein('abc', 'abc')).toBe(0)
+  })
+
+  test('single insertion', () => {
+    expect(levenshtein('abc', 'abcd')).toBe(1)
+  })
+
+  test('single deletion', () => {
+    expect(levenshtein('abcd', 'abc')).toBe(1)
+  })
+
+  test('single substitution', () => {
+    expect(levenshtein('abc', 'axc')).toBe(1)
+  })
+
+  test('transposition counts as 2', () => {
+    expect(levenshtein('mpc', 'mcp')).toBe(2)
+  })
+
+  test('empty strings', () => {
+    expect(levenshtein('', '')).toBe(0)
+    expect(levenshtein('abc', '')).toBe(3)
+    expect(levenshtein('', 'abc')).toBe(3)
+  })
+})
+
+describe('suggest', () => {
+  const commands = ['deploy', 'status', 'list', 'create']
+
+  test('returns closest match within threshold', () => {
+    expect(suggest('deplyo', commands)).toBe('deploy')
+  })
+
+  test('returns match for transposition', () => {
+    expect(suggest('mpc', ['mcp', 'skills', 'completions'])).toBe('mcp')
+  })
+
+  test('returns undefined when no match is close enough', () => {
+    expect(suggest('xyz', commands)).toBeUndefined()
+  })
+
+  test('returns undefined for empty candidates', () => {
+    expect(suggest('deploy', [])).toBeUndefined()
+  })
+
+  test('picks the closest among multiple candidates', () => {
+    expect(suggest('craete', ['list', 'create', 'delete'])).toBe('create')
+  })
+
+  test('matches unambiguous prefix', () => {
+    expect(suggest('ski', ['mcp', 'skills', 'completions'])).toBe('skills')
+  })
+
+  test('prefers shorter prefix match among ambiguous prefixes', () => {
+    expect(suggest('ski', ['skills', 'skip'])).toBe('skip')
+  })
+
+  test('prefix match beats fuzzy match', () => {
+    expect(suggest('iss', ['issue', 'is', 'miss'])).toBe('issue')
+  })
+
+  test('contains match beats fuzzy match', () => {
+    expect(suggest('sue', ['issue', 'use', 'sum'])).toBe('issue')
+  })
+
+  test('case-insensitive matching', () => {
+    expect(suggest('Deploy', ['deploy', 'list'])).toBe('deploy')
+  })
+})

package/src/internal/helpers.ts

@@ -0,0 +1,59 @@
+/** Checks whether a value is a plain object record. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Converts a camelCase string to kebab-case. */
+export function toKebab(value: string): string {
+  return value.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)
+}
+
+/** Computes the Levenshtein edit distance between two strings. */
+export function levenshtein(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[] = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    let prev = dp[0]!
+    dp[0] = i
+    for (let j = 1; j <= n; j++) {
+      const tmp = dp[j]!
+      dp[j] = a[i - 1] === b[j - 1] ? prev : 1 + Math.min(prev, dp[j]!, dp[j - 1]!)
+      prev = tmp
+    }
+  }
+  return dp[n]!
+}
+
+/** Suggests the closest command name from a set, returning it if within a reasonable edit distance. */
+export function suggest(input: string, candidates: Iterable<string>): string | undefined {
+  const threshold = input.length <= 4 ? 2 : Math.floor(input.length / 2)
+  const lower = input.toLowerCase()
+  const all = Array.isArray(candidates) ? candidates : [...candidates]
+
+  let best: string | undefined
+  let bestScore = Infinity
+
+  for (const c of all) {
+    const lc = c.toLowerCase()
+    const dist = levenshtein(lower, lc)
+
+    let score: number
+    if (lc.startsWith(lower) && lc !== lower)
+      // prefix match — best tier
+      score = dist
+    else if (lc.includes(lower))
+      // contains match — middle tier
+      score = 100 + dist
+    else if (dist <= threshold)
+      // fuzzy match — last tier
+      score = 200 + dist
+    else continue
+
+    if (score < bestScore) {
+      bestScore = score
+      best = c
+    }
+  }
+  return best
+}

package/src/middleware.ts

@@ -10,16 +10,11 @@ type InferVars<vars extends z.ZodObject<any> | undefined> =
 type InferEnv<env extends z.ZodObject<any> | undefined> =
   env extends z.ZodObject<any> ? z.output<env> : {}
 
-/** @internal Infers the output type of an options schema, or `{}` if undefined. */
-type InferOptions<options extends z.ZodObject<any> | undefined> =
-  options extends z.ZodObject<any> ? z.output<options> : {}
-
 /** Middleware handler that runs before/after command execution. */
 export type Handler<
   vars extends z.ZodObject<any> | undefined = undefined,
   env extends z.ZodObject<any> | undefined = undefined,
-  options extends z.ZodObject<any> | undefined = undefined,
-> = (context: Context<vars, env, options>, next: () => Promise<void>) => Promise<void> | void
+> = (context: Context<vars, env>, next: () => Promise<void>) => Promise<void> | void
 
 /** CTA block for middleware error/ok responses. */
 type CtaBlock = {
@@ -33,12 +28,13 @@ type CtaBlock = {
 export type Context<
   vars extends z.ZodObject<any> | undefined = undefined,
   env extends z.ZodObject<any> | undefined = undefined,
-  options extends z.ZodObject<any> | undefined = undefined,
 > = {
   /** Whether the consumer is an agent (stdout is not a TTY). */
   agent: boolean
   /** The resolved command path. */
   command: string
+  /** The binary name the user invoked (e.g. an alias). Falls back to `name` when not resolvable. */
+  displayName: string
   /** Parsed environment variables from the CLI-level env schema. */
   env: InferEnv<env>
   /** Return an error result, short-circuiting the middleware chain. */
@@ -55,8 +51,6 @@ export type Context<
   formatExplicit: boolean
   /** The CLI name. */
   name: string
-  /** Parsed options from the root CLI-level options schema. */
-  options: InferOptions<options>
   /** Set a typed variable for downstream middleware and handlers. */
   set<key extends string & keyof InferVars<vars>>(key: key, value: InferVars<vars>[key]): void
   /** Variables set by upstream middleware. */
@@ -65,11 +59,10 @@ export type Context<
   version: string | undefined
 }
 
-/** Creates a strictly typed middleware handler. Pass the vars schema as a generic for typed `c.set()` and `c.var`, the env schema for typed `c.env`, and the options schema for typed `c.options`. */
+/** Creates a strictly typed middleware handler. Pass the vars schema as a generic for typed `c.set()` and `c.var`, and the env schema for typed `c.env`. */
 export default function middleware<
   const vars extends z.ZodObject<any> | undefined = undefined,
   const env extends z.ZodObject<any> | undefined = undefined,
-  const options extends z.ZodObject<any> | undefined = undefined,
->(handler: Handler<vars, env, options>): Handler<vars, env, options> {
+>(handler: Handler<vars, env>): Handler<vars, env> {
   return handler
 }