Module: RosettAi::Deprecation

Defined in:
lib/rosett_ai/deprecation.rb

Overview

Structured deprecation warning system.

Emits formatted warnings to stderr when deprecated features are used, including the version where deprecation started and the planned removal version. Warnings are deduplicated per session to avoid noise.

See Also:

  • conf/design/backward_compatibilityconf/design/backward_compatibility.yml

Author:

  • hugo

  • claude

Class Method Summary collapse

Class Method Details

.already_warned?(feature) ⇒ Boolean

Check whether a feature has already been warned in this session.

Parameters:

  • feature (String)

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/rosett_ai/deprecation.rb', line 47

def already_warned?(feature)
  @mutex.synchronize { @warned.key?(feature) }
end

.reset!

This method returns an undefined value.

Reset all warned state. Intended for test isolation.



54
55
56
 
# File 'lib/rosett_ai/deprecation.rb', line 54

def reset!
  @mutex.synchronize { @warned = {} }
end

.warn_deprecated(feature:, replacement:, since:, removal:, stderr: $stderr)

This method returns an undefined value.

Emit a deprecation warning for a feature.

Deduplicates by feature name — a second call for the same feature within the same process is silently ignored.

Parameters:

  • feature (String) —

    the deprecated feature name (e.g. "--target")

  • replacement (String) —

    the replacement (e.g. "--engine")

  • since (String) —

    version when deprecation started (e.g. "1.1.0")

  • removal (String) —

    version when feature will be removed (e.g. "2.0.0")

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

    output stream for warnings (default: $stderr)



34
35
36
37
38
39
40
41
 
# File 'lib/rosett_ai/deprecation.rb', line 34

def warn_deprecated(feature:, replacement:, since:, removal:, stderr: $stderr)
  return if already_warned?(feature)

  mark_warned(feature)
  message = format_message(feature: feature, replacement: replacement, since: since, removal: removal)
  formatted = tty?(stderr) ? Rainbow(message).yellow : message
  stderr.puts formatted
end