Module: ClaudeMemory::Deprecations

Defined in:
lib/claude_memory/deprecations.rb

Overview

Soft-rename / soft-removal mechanism for public-API surfaces. Used to mark an old name (CLI flag, MCP tool, Ruby method, hook field, predicate) as deprecated in ‘N.x.0` releases while keeping it functional for at least one minor cycle, with explicit removal no earlier than `(N+1).0.0`. This deprecation policy is documented in `docs/api_stability.md`.

Two suppression mechanisms keep deprecation noise manageable:

  • **Per-call-site dedupe**: same (name, caller_file:line) pair only emits once per process. Prevents tight loops or repeated callers from drowning the terminal.

  • **Env var opt-out**: ‘CLAUDE_MEMORY_NO_DEPRECATIONS=1` silences everything. Recommended for test fixtures and CI runs that knowingly exercise legacy paths.

Examples:

Deprecate a renamed CLI flag

ClaudeMemory::Deprecations.warn(
  name: "claude-memory recall --legacy-mode",
  replacement: "--mode=legacy",
  removed_in: "1.0.0"
)

Deprecate a soft-renamed Ruby method

ClaudeMemory::Deprecations.warn(
  name: "ClaudeMemory::Recall#legacy_query",
  replacement: "Recall#query",
  removed_in: "1.0.0",
  message: "Pass `mode: :legacy` to #query instead."
)

Constant Summary collapse

ENV_OPT_OUT = 
"CLAUDE_MEMORY_NO_DEPRECATIONS"

Class Method Summary collapse

Class Method Details

.reset! ⇒ Object

Wipe the per-call-site dedupe state. Test-only — production callers should rely on the per-process behavior.



80
81
82
 
# File 'lib/claude_memory/deprecations.rb', line 80

def reset!
  @mutex.synchronize { @emitted.clear }
end

.warn(name:, replacement: nil, removed_in: nil, message: nil, caller_location: nil, output: $stderr) ⇒ Boolean

Emit a deprecation warning to ‘output` (stderr by default).

Parameters:

  • name (String) —

    the deprecated identifier (CLI flag, method, tool name, etc.). Be specific: “ClaudeMemory::Recall#query(:legacy)” beats “Recall#query”.

  • replacement (String, nil) (defaults to: nil) —

    what users should switch to. Optional but strongly recommended — a deprecation without a migration path is annoying.

  • removed_in (String, nil) (defaults to: nil) —

    target removal version, semver string. Conventionally the next major (‘(N+1).0.0`).

  • message (String, nil) (defaults to: nil) —

    free-form extra context. Use for subtle migration nuance the replacement string can’t capture.

  • caller_location (String, nil) (defaults to: nil) —

    override for testing.

  • output (IO) (defaults to: $stderr) —

    override for testing. Default: $stderr.

Returns:

  • (Boolean) —

    true if a warning was emitted, false if suppressed (env opt-out or already-emitted dedupe).



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/claude_memory/deprecations.rb', line 61

def warn(name:, replacement: nil, removed_in: nil, message: nil,
  caller_location: nil, output: $stderr)
  return false if suppressed?

  location = caller_location || derive_caller_location
  key = "#{name}@#{location}"

  @mutex.synchronize do
    return false if @emitted[key]
    @emitted[key] = true
  end

  output.puts(format_warning(name: name, replacement: replacement,
    removed_in: removed_in, message: message, location: location))
  true
end