rspec-openapi 0.34.0 → 0.36.0

data/lib/rspec/openapi/schema_builder.rb

@@ -5,13 +5,32 @@ require_relative 'schema_builder/build_context'
 require_relative 'schema_builder/variation_merger'
 
 class << RSpec::OpenAPI::SchemaBuilder
+  # Record members holding the per-context lookup maps, by context (and kind).
+  ENUM_MEMBERS = { request: :request_enum, response: :response_enum }.freeze
+  READ_ONLY_MEMBERS = { request: :request_read_only, response: :response_read_only }.freeze
+  OVERRIDE_MEMBERS = {
+    additional_properties: {
+      request: :request_additional_properties, response: :response_additional_properties,
+    },
+    hybrid_additional_properties: {
+      request: :request_hybrid_additional_properties, response: :response_hybrid_additional_properties,
+    },
+  }.freeze
+
+  # GET and DELETE never have a request body in OpenAPI.
+  BODYLESS_METHODS = ['delete', 'get'].freeze
+
+  # The schema holds symbol keys like the document, and nothing of the record:
+  # the data it carries is copied, so the merger can take the schema over.
+  #
   # @param [RSpec::OpenAPI::Record] record
   # @return [Hash]
   def build(record)
+    http_method = record.http_method.downcase
     {
       paths: {
-        normalize_path(record.path) => {
-          record.http_method.downcase => build_operation(record),
+        normalize_path(record.path).to_sym => {
+          http_method.to_sym => build_operation(record, http_method),
         },
       },
     }
@@ -19,20 +38,19 @@ class << RSpec::OpenAPI::SchemaBuilder
 
   private
 
-  def build_operation(record)
-    http_method = record.http_method.downcase
-    # GET and DELETE never have a request body in OpenAPI.
-    request_body = ['delete', 'get'].include?(http_method) ? nil : build_request_body(record)
-    {
+  def build_operation(record, http_method)
+    operation = {
       summary: record.summary,
-      tags: record.tags,
+      tags: copy(record.tags),
       operationId: record.operation_id,
-      security: record.security,
+      security: copy(record.security),
       deprecated: record.deprecated ? true : nil,
       parameters: build_parameters(record),
-      requestBody: request_body,
-      responses: { record.status.to_s => build_response(record) },
-    }.compact
+      requestBody: BODYLESS_METHODS.include?(http_method) ? nil : build_request_body(record),
+      responses: { record.status.to_s.to_sym => build_response(record) },
+    }
+    operation.compact!
+    operation
   end
 
   def build_response(record)
@@ -56,18 +74,18 @@ class << RSpec::OpenAPI::SchemaBuilder
   def build_content(record)
     disposition = normalize_content_disposition(record.response_content_disposition)
     content_type = normalize_content_type(record.response_content_type)
-    ctx = BuildContext.new(record: record, context: :response)
+    ctx = BuildContext.root(record, :response)
 
     if RSpec::OpenAPI.supports_item_schema? && RSpec::OpenAPI.sequential_media_type?(content_type)
       item_schema = build_stream_item_schema(record.response_body, content_type, ctx)
-      return { content_type => { itemSchema: item_schema } } if item_schema
+      return { content_type.to_sym => { itemSchema: item_schema } } if item_schema
     end
 
     schema = build_property(record.response_body, ctx, disposition: disposition)
     example = response_example(record, disposition: disposition)
 
     body = build_example_body(schema, record, mode: record.response_example_mode, example: example)
-    { content_type => body }
+    { content_type.to_sym => body }
   end
 
   def build_stream_item_schema(raw, content_type, ctx)
@@ -85,18 +103,30 @@ class << RSpec::OpenAPI::SchemaBuilder
 
     case mode
     when :multiple
-      { schema: schema, examples: { record.example_key => build_named_example(record, example) } }
+      { schema: schema, examples: { example_name(record) => build_named_example(record, example) } }
     else
       # :single (default)
       # :single may emit nil example or nil _example_summary; compact strips them.
-      { schema: schema, example: example, **example_metadata(record) }.compact
+      body = {
+        schema: schema,
+        example: example,
+        _example_key: record.example_key,
+        _example_summary: example_summary(record),
+      }
+      body.compact!
+      body
     end
   end
 
   def response_example(record, disposition:)
-    return nil if !example_enabled?(record) || disposition
+    return nil if !example_enabled?(record) || disposition || record.response_example_mode == :none
+
+    build_example(record.response_body)
+  end
 
-    record.response_body
+  # Named like the loader names the examples it reads back.
+  def example_name(record)
+    RSpec::OpenAPI::ExampleKey.normalize(record.example_key).to_sym
   end
 
   def build_named_example(record, value)
@@ -104,10 +134,6 @@ class << RSpec::OpenAPI::SchemaBuilder
     summary ? { summary: summary, value: value } : { value: value }
   end
 
-  def example_metadata(record)
-    { _example_key: record.example_key, _example_summary: example_summary(record) }
-  end
-
   def example_summary(record)
     return nil unless RSpec::OpenAPI.enable_example_summary
     return nil if record.example_name.nil? || record.example_name.empty?
@@ -123,15 +149,12 @@ class << RSpec::OpenAPI::SchemaBuilder
     parameters = record.path_params.map do |key, value|
       build_parameter(key, value, location: 'path', record: record)
     end
-
-    parameters += flatten_query_params(record.query_params).map do |key, value|
-      build_parameter(key, value, location: 'query', record: record)
+    flatten_query_params(record.query_params).each do |key, value|
+      parameters << build_parameter(key, value, location: 'query', record: record)
     end
-
-    parameters += record.request_headers.map do |key, value|
-      build_parameter(key, value, location: 'header', record: record)
+    record.request_headers.each do |key, value|
+      parameters << build_parameter(key, value, location: 'header', record: record)
     end
-
     parameters.empty? ? nil : parameters
   end
 
@@ -141,21 +164,26 @@ class << RSpec::OpenAPI::SchemaBuilder
     is_query = location == 'query'
     required = is_query ? record.required_request_params.include?(key) : true
     cast = try_cast(value)
-    ctx = BuildContext.new(record: record, context: :request, key: key, path: key.to_s)
-    {
-      name: key.to_s,
+    name = key.to_s
+    ctx = BuildContext.root(record, :request, name, key)
+    parameter = {
+      name: name,
       in: location,
       required: required,
       schema: build_property(cast, ctx),
       example: (cast if example_enabled?(record)),
-    }.compact
+    }
+    parameter.compact!
+    parameter
   end
 
   def build_response_headers(record)
-    record.response_headers.to_h do |key, value|
-      ctx = BuildContext.new(record: record, context: :response, key: key, path: key.to_s)
-      [key, { schema: build_property(try_cast(value), ctx) }]
+    headers = {}
+    record.response_headers.each do |key, value|
+      ctx = BuildContext.root(record, :response, key.to_s, key)
+      headers[key.to_sym] = { schema: build_property(try_cast(value), ctx) }
     end
+    headers
   end
 
   def flatten_query_params(params, parent_key = nil)
@@ -175,12 +203,12 @@ class << RSpec::OpenAPI::SchemaBuilder
     return nil if record.status >= 400 && record.request_example_mode != :multiple
 
     content_type = normalize_content_type(record.request_content_type)
-    ctx = BuildContext.new(record: record, context: :request)
+    ctx = BuildContext.root(record, :request)
     schema = build_property(record.request_params, ctx)
-    example = example_enabled?(record) ? build_example(record.request_params) : nil
+    example = build_example(record.request_params) if example_enabled?(record) && record.request_example_mode != :none
 
     body = build_example_body(schema, record, mode: record.request_example_mode, example: example)
-    { content: { content_type => body } }
+    { content: { content_type.to_sym => body } }
   end
 
   def build_property(value, ctx, disposition: nil)
@@ -203,14 +231,25 @@ class << RSpec::OpenAPI::SchemaBuilder
     if override.is_a?(Hash) && !override.empty?
       # Schema override: the object's keys are dynamic — replace captured
       # `properties` / `required` with the supplied dictionary value schema.
-      property[:additionalProperties] = override
+      property[:additionalProperties] = copy(override)
       return
     end
 
-    property[:properties] = value.to_h do |k, v|
-      [k, build_property(v, ctx.descend(k))]
+    # Only an object property can be readOnly. A request that sends a candidate
+    # says false, which wins where the two sides meet in one schema (see
+    # SchemaMerger).
+    read_only = ctx.record[READ_ONLY_MEMBERS.fetch(ctx.context)]
+    properties = {}
+    required = []
+    value.each do |k, v|
+      child = build_property(v, ctx.descend(k))
+      name = k.to_s
+      child[:readOnly] = ctx.context == :response if read_only&.[](name)
+      properties[name.to_sym] = child
+      required << name
     end
-    property[:required] = property[:properties].keys
+    property[:properties] = properties
+    property[:required] = required
     apply_additional_properties(property, override,
                                 infer_override(ctx.path, ctx.record, ctx.context, :hybrid_additional_properties),)
   end
@@ -224,7 +263,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     if [true, false].include?(override)
       property[:additionalProperties] = override
     elsif hybrid_override.is_a?(Hash) && !hybrid_override.empty?
-      property[:additionalProperties] = hybrid_override
+      property[:additionalProperties] = copy(hybrid_override)
     end
   end
 
@@ -245,7 +284,7 @@ class << RSpec::OpenAPI::SchemaBuilder
                end
              end
 
-    result[:enum] = enum if enum
+    result[:enum] = copy(enum) if enum
     result
   end
 
@@ -259,7 +298,7 @@ class << RSpec::OpenAPI::SchemaBuilder
     return nil if !path || !record
 
     # Keys are already normalized to strings by SharedExtractor.normalize_enum
-    record.send("#{context}_enum")&.[](path.to_s)
+    record[ENUM_MEMBERS.fetch(context)]&.[](path.to_s)
   end
 
   # Looks up an override for the current path under one of the per-context
@@ -268,7 +307,7 @@ class << RSpec::OpenAPI::SchemaBuilder
   # distinguishable from "no override"; for :hybrid_additional_properties
   # plain lookup is enough because only Hash values are meaningful.
   def infer_override(path, record, context, kind)
-    overrides = record.send("#{context}_#{kind}")
+    overrides = record[OVERRIDE_MEMBERS.fetch(kind).fetch(context)]
     return nil unless overrides
 
     # path is nil at the body root; nil.to_s == '' lets users target it via { '' => ... }.
@@ -282,36 +321,39 @@ class << RSpec::OpenAPI::SchemaBuilder
     return true if value == 'true'
     return false if value == 'false'
 
-    Integer(value)
-  rescue TypeError, ArgumentError
-    value
+    Integer(value, exception: false) || value
   end
 
+  # A copy of a recorded value with symbol keys, and the filename of an upload.
   def build_example(value)
-    return nil if value.nil?
-
-    adjust_value(value.dup)
-  end
-
-  def adjust_params(hash)
-    hash.transform_values! { |v| adjust_value(v) }
-  end
-
-  def adjust_value(value)
     case value
+    when Hash
+      example = {}
+      value.each { |key, item| example[key.to_sym] = build_example(item) }
+      example
+    when Array then value.map { |item| build_example(item) }
     when ActionDispatch::Http::UploadedFile then value.original_filename
-    when Hash then adjust_params(value)
-    when Array then value.map { |item| adjust_value(item) }
     else value
     end
   end
 
+  # A record may hold what the metadata of a whole example group holds.
+  def copy(value)
+    RSpec::OpenAPI::KeyTransformer.symbolize(value)
+  end
+
+  # gsub copies the path even when nothing matches.
   def normalize_path(path)
+    return path unless path.include?(':')
+
     path.gsub(%r{/:([^:/]+)}, '/{\1}')
   end
 
+  # sub copies the content type even when it carries no parameters.
   def normalize_content_type(content_type)
-    content_type&.sub(/;.+\z/, '')
+    return content_type unless content_type&.include?(';')
+
+    content_type.sub(/;.+\z/, '')
   end
 
   # Same logic as normalize_content_type – strips header parameters after ';'

data/lib/rspec/openapi/schema_cleaner.rb

@@ -13,8 +13,15 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   def cleanup_components_schemas!(base, spec)
     cleanup_hash!(base, spec, 'components.schemas.*')
     cleanup_hash!(base, spec, 'components.schemas.*.properties.*')
+    cleanup_one_of_properties!(base, spec, 'components.schemas.*')
   end
 
+  # The request and response bodies, where most of the cleanup happens.
+  MEDIA_TYPE_SELECTORS = [
+    'paths.*.*.requestBody.content.application/json',
+    'paths.*.*.responses.*.content.application/json',
+  ].freeze
+
   # Cleanup specific elements that exists in the base but not in the spec
   #
   # @param [Hash] base
@@ -29,18 +36,16 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     # cleanup parameters
     cleanup_array!(base, spec, 'paths.*.*.parameters', [:name, :in])
 
-    # cleanup requestBody
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.example.*')
-    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.examples.*')
-
-    # cleanup responses
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.schema.properties.*')
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.example.*')
-    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.examples.*')
+    # cleanup request and response bodies, each walked down to once
+    MEDIA_TYPE_SELECTORS.each do |selector|
+      RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, media_type, fresh|
+        cleanup_media_type!(media_type, fresh)
+      end
+    end
 
-    # cleanup temporary fields used for internal processing
-    cleanup_temporary_fields!(base)
+    # A full run decides readOnly anew, so a property no request sends any
+    # more stops being held at false.
+    RSpec::OpenAPI::HashHelper.each_schema(base.dig(:components, :schemas)) { |schema| delete_false_read_only!(schema) }
 
     base
   end
@@ -50,52 +55,72 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
     return if security_schemes.empty?
 
-    paths_to_security_definitions = RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'security')
-
-    paths_to_security_definitions.each do |path|
-      parent_path_definition = base.dig(*path.take(path.length - 1))
-
+    each_operation(base) do |operation|
       security_schemes.each do |security_scheme_name, security_scheme|
-        remove_parameters_conflicting_with_security_scheme!(
-          parent_path_definition, security_scheme, security_scheme_name,
-        )
+        remove_parameters_conflicting_with_security_scheme!(operation, security_scheme, security_scheme_name)
       end
     end
   end
 
-  def cleanup_empty_required_array!(base)
-    paths_to_objects = [
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties'),
-      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'properties'),
-    ]
-    paths_to_objects.each do |path|
-      parent = base.dig(*path.take(path.length - 1))
-      next unless parent
-
-      # "required" array  must not be present if empty
-      parent.delete(:required) if parent[:required] && parent[:required].empty?
+  # One walk over the schemas once the components are updated, which also drops
+  # the fields the builder left for the merge. `readOnly: false` is how a
+  # request says it sends a candidate property. A component shared by a request
+  # and a response keeps it, or a later partial run that sees only the response
+  # would flip it back to true. Inline under paths each side has its own
+  # schema, so there it says nothing.
+  def cleanup_schemas!(base)
+    RSpec::OpenAPI::HashHelper.each_schema(base.dig(:components, :schemas)) do |schema|
+      delete_temporary_fields!(schema)
+      delete_empty_required!(schema)
+    end
+    RSpec::OpenAPI::HashHelper.each_schema(base[:paths]) do |schema|
+      delete_temporary_fields!(schema)
+      delete_empty_required!(schema)
+      delete_false_read_only!(schema)
     end
   end
 
   private
 
-  # Recursively remove temporary fields like :_example_key and :_example_name from the schema.
-  # Every caller has already established that it holds a Hash.
-  def cleanup_temporary_fields!(hash)
-    hash.delete(:_example_key)
-    hash.delete(:_example_summary)
-    hash.delete(:_example_name)
-    if (fallback = hash.delete(:_fallback_description))
-      hash[:description] ||= fallback
-    end
+  # The description of a response whose example is not recorded is provisional,
+  # so it stays only where no documented test set one.
+  def delete_temporary_fields!(schema)
+    schema.delete(:_example_key)
+    schema.delete(:_example_summary)
+    schema.delete(:_example_name)
+    return unless (fallback = schema.delete(:_fallback_description))
 
-    hash.each_value do |value|
-      case value
-      when Hash
-        cleanup_temporary_fields!(value)
-      when Array
-        value.each { |item| cleanup_temporary_fields!(item) if item.is_a?(Hash) }
-      end
+    schema[:description] ||= fallback
+  end
+
+  # A recorded example is data, so a field in it named `required` stays however
+  # it is shaped. An empty `required` must not be present.
+  def delete_empty_required!(schema)
+    schema.delete(:required) if schema.key?(:properties) && schema[:required] && schema[:required].empty?
+  end
+
+  def delete_false_read_only!(schema)
+    schema.delete(:readOnly) if schema[:readOnly] == false
+  end
+
+  # The selectors are relative to the media type. A media type the spec does
+  # not hold has no fresh counterpart, and all of its entries are stale.
+  def cleanup_media_type!(media_type, fresh)
+    cleanup_hash!(media_type, fresh, 'schema.properties.*')
+    cleanup_hash!(media_type, fresh, 'example.*')
+    cleanup_hash!(media_type, fresh, 'examples.*')
+
+    # cleanup properties of each variant once a body became a oneOf
+    cleanup_one_of_properties!(media_type, fresh, 'schema')
+  end
+
+  # Security sits on operations, the hashes under a path item: a non-standard
+  # method is still inline here and only moves under additionalOperations later.
+  def each_operation(base)
+    base[:paths].each_value do |path_item|
+      next unless path_item.is_a?(Hash)
+
+      path_item.each_value { |operation| yield operation if operation.is_a?(Hash) }
     end
   end
 
@@ -113,33 +138,54 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
   end
 
   def cleanup_array!(base, spec, selector, fields_for_identity)
-    marshal = lambda do |obj|
-      Marshal.dump(obj.slice(*fields_for_identity))
-    end
+    identity = ->(obj) { fields_for_identity.map { |field| obj[field] } }
 
-    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
-      target_array = base.dig(*paths)
-      spec_array = spec.dig(*paths)
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, target_array, spec_array|
       next unless target_array.is_a?(Array) && spec_array.is_a?(Array)
 
-      spec_identities = Set.new(spec_array.map(&marshal))
-      target_array.select! { |e| spec_identities.include?(marshal.call(e)) }
-      target_array.sort_by! { |param| fields_for_identity.map { |f| param[f] }.join('-') }
+      spec_identities = Set.new(spec_array.map(&identity))
+      target_array.select! { |e| spec_identities.include?(identity.call(e)) }
+      target_array.sort_by! { |param| identity.call(param).join('-') }
       # Keep the last duplicate to produce the result stably
-      deduplicated = target_array.reverse.uniq { |param| param.slice(*fields_for_identity) }.reverse
+      deduplicated = target_array.reverse.uniq(&identity).reverse
       target_array.replace(deduplicated)
     end
     base
   end
 
-  # Every selector above names at least two segments, so a matched path always
-  # has a parent to delete the entry from.
+  def cleanup_one_of_properties!(base, spec, selector)
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |_parent, _key, schema, fresh|
+      next unless schema.is_a?(Hash) && fresh.is_a?(Hash)
+
+      variants = schema[:oneOf]
+      next unless variants.is_a?(Array)
+
+      variants.each { |variant| cleanup_variant_properties!(variant, variants, fresh) }
+    end
+    base
+  end
+
+  # Variants are matched by type, since the spec may hold one of them as a bare
+  # schema or in another order. Two variants of one type can not be told apart
+  # that way, so those stay as they are, like a variant of a type the spec does
+  # not hold.
+  def cleanup_variant_properties!(variant, variants, fresh)
+    return unless variant.is_a?(Hash) && variant[:properties].is_a?(Hash)
+    return unless variants.one? { |other| other.is_a?(Hash) && other[:type] == variant[:type] }
+
+    counterpart = RSpec::OpenAPI::HashHelper.variant_of_type(fresh, variant[:type])
+    return unless counterpart
+
+    variant[:properties].delete_if { |name, _| counterpart.dig(:properties, name).nil? }
+  end
+
+  # The stale entries are deleted after the walk, which iterates their parents.
   def cleanup_hash!(base, spec, selector)
-    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
-      exist_in_base = !base.dig(*paths).nil?
-      not_in_spec = spec.dig(*paths).nil?
-      base.dig(*paths[0..-2]).delete(paths.last) if exist_in_base && not_in_spec
+    stale = nil
+    RSpec::OpenAPI::HashHelper.each_matched(base, spec, selector) do |parent, key, value, counterpart|
+      (stale ||= []) << [parent, key] if !value.nil? && counterpart.nil?
     end
+    stale&.each { |parent, key| parent.delete(key) }
     base
   end
 end

data/lib/rspec/openapi/schema_file.rb

@@ -3,11 +3,11 @@
 require 'fileutils'
 require 'yaml'
 require 'json'
+require 'stringio'
 
 # For Ruby 2.7
 require 'date'
 
-# TODO: Support JSON
 class RSpec::OpenAPI::SchemaFile
   # @param [String] path
   def initialize(path)
@@ -16,28 +16,24 @@ class RSpec::OpenAPI::SchemaFile
 
   # Reads the existing spec, lets the block mutate it, writes the result back
   # and returns the (symbolized) spec so it can be mirrored to other files.
+  # A document that does not load is left as it is.
   # @return [Hash]
-  def edit(&block)
+  def edit
     spec = read
-    block.call(spec)
+    begin
+      yield spec
+    ensure
+      write(spec)
+    end
     spec
-  ensure
-    write(spec)
   end
 
   # Writes an already-built spec to this file, choosing the format from the
-  # file extension.
+  # file extension. Both formats write the symbol keys as strings themselves.
   # @param [Hash] spec
   def write(spec)
-    stringified = RSpec::OpenAPI::KeyTransformer.stringify(spec)
     FileUtils.mkdir_p(File.dirname(@path))
-    output =
-      if json?
-        JSON.pretty_generate(stringified)
-      else
-        prepend_comment(YAML.dump(stringified))
-      end
-    File.write(@path, output)
+    File.write(@path, json? ? JSON.pretty_generate(spec) : yaml_document(spec))
   end
 
   private
@@ -46,18 +42,29 @@ class RSpec::OpenAPI::SchemaFile
   def read
     return {} unless File.exist?(@path)
 
-    content = YAML.safe_load(File.read(@path), permitted_classes: [Date, Time]) # this can also parse JSON
-    return {} if content.nil?
+    content = File.read(@path)
+    spec = json? ? read_json(content) : RSpec::OpenAPI::YAMLLoader.load(content)
+    spec.nil? ? {} : spec
+  end
+
+  def read_json(content)
+    return nil if content.match?(/\A\s*\z/)
 
-    RSpec::OpenAPI::KeyTransformer.symbolize(content)
+    spec = JSON.parse(content, symbolize_names: true, max_nesting: false)
+    RSpec::OpenAPI::KeyTransformer.normalize_example_names!(spec)
   end
 
-  def prepend_comment(content)
-    return content if RSpec::OpenAPI.comment.nil?
+  def yaml_document(spec)
+    io = StringIO.new(+'')
+    io.write(comment_lines) unless RSpec::OpenAPI.comment.nil?
+    RSpec::OpenAPI::YAMLDumper.dump(spec, io)
+    io.string
+  end
 
+  def comment_lines
     comment = RSpec::OpenAPI.comment.dup
     comment << "\n" unless comment.end_with?("\n")
-    "#{comment.gsub(/^/, '# ').gsub(/^# \n/, "#\n")}#{content}"
+    comment.gsub(/^/, '# ').gsub(/^# \n/, "#\n")
   end
 
   def json?