andromeda_cms 0.1.0-aarch64-linux-musl

data/lib/generators/andromeda/component/component_generator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "andromeda_cms"
+require "active_support/core_ext/string/inflections"
+
+module Andromeda
+  module Generators
+    # `rails g andromeda:component NAME [prop ...]` -- a starter
+    # partial for an MDX component, named by convention
+    # (`Callout` -> `_callout.html.erb`) so no registration step is
+    # needed for the common case.
+    class ComponentGenerator < Rails::Generators::NamedBase
+      argument :props, type: :array, default: [], banner: "prop prop"
+
+      # An MDX tag is a single JSX identifier (`<Callout>`), never a
+      # namespaced or dotted one -- reject anything NamedBase's own parsing
+      # would otherwise silently accept (e.g. it treats `foo/bar` as a
+      # namespace and `foo.bar` as one odd file name).
+      VALID_NAME_RE = /\A[A-Za-z][A-Za-z0-9_]*\z/
+
+      def validate_component_name!
+        return if name.match?(VALID_NAME_RE)
+
+        raise ArgumentError,
+              "invalid component name #{name.inspect} -- use a single CamelCase or underscored word " \
+              "(e.g. `Callout` or `callout`); it becomes " \
+              "#{Andromeda.config.components_path}/_#{name.underscore}.html.erb"
+      end
+
+      def create_partial
+        create_file "#{Andromeda.config.components_path}/_#{underscored_name}.html.erb", partial_content
+      end
+
+      private
+
+      def underscored_name
+        name.underscore
+      end
+
+      def tag_name
+        name.camelize
+      end
+
+      def partial_content
+        <<~ERB
+          #{usage_comment}
+          <div class="#{underscored_name.dasherize}">
+          #{prop_lines.join("\n")}#{"\n" unless prop_lines.empty?}  <%= content %>
+          </div>
+        ERB
+      end
+
+      def prop_lines
+        props.map do |prop|
+          local = prop.underscore
+          "  <% if local_assigns[:#{local}] %><p class=\"#{underscored_name.dasherize}__#{local.dasherize}\">" \
+            "<%= #{local} %></p><% end %>"
+        end
+      end
+
+      def usage_comment
+        attrs = props.map { |prop| "#{prop.underscore.camelize(:lower)}=\"...\"" }.join(" ")
+        opening = attrs.empty? ? "<#{tag_name}>" : "<#{tag_name} #{attrs}>"
+
+        <<~ERB.chomp
+          <%# MDX usage:
+                #{opening}
+                  Body text.
+                </#{tag_name}>
+          %>
+        ERB
+      end
+    end
+  end
+end

data/lib/generators/andromeda/import_astro/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Imports an existing Astro project's content into this app: every
+    collection referenced by `src/content.config.ts` (or, failing that,
+    every directory under `src/content/`) into `app/content/<collection>/`,
+    `src/assets` into `app/assets/`, an `Andromeda::Entry` subclass per
+    collection under `app/models/content/`, and a starter partial for every
+    MDX component that does not have one yet.
+
+    Frontmatter keys are rewritten to snake_case and MDX import statements
+    are rewritten to the `content_components/...` partial-path form;
+    everything else is copied byte-for-byte.
+
+    Prints a migration report of what was copied/rewritten/generated, and
+    everything that still needs a human (unmapped schema fields, components
+    to implement, expressions the renderer cannot statically evaluate).
+
+Example:
+    rails generate andromeda:import_astro ../my-astro-blog
+
+    rails generate andromeda:import_astro ../my-astro-blog --dry-run
+        Prints the same report without writing any files.

data/lib/generators/andromeda/import_astro/astro_schema_json.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Andromeda
+  module Generators
+    module ImportAstro
+      # Astro writes a resolved JSON Schema per collection to
+      # `.astro/collections/<name>.schema.json` whenever it has run at least
+      # once (`astro sync`/`astro dev`/`astro build`). This
+      # generator prefers that file over parsing `content.config.ts` by
+      # hand when it is available.
+      #
+      # In practice the two sources are complementary rather than one
+      # strictly superseding the other:
+      #
+      # - The JSON Schema is Astro's own fully-resolved output -- it reflects
+      #   whatever Zod actually decided about `required`/type after unions,
+      #   refinements, etc., which a regex over the TypeScript source can
+      #   only approximate. It is therefore the more trustworthy source for
+      #   **required-ness** and for telling `z.number()` (JSON Schema
+      #   `"number"`) apart from a `.int()`-refined one (`"integer"`).
+      # - It cannot tell `image()`/`reference(...)` apart from a plain
+      #   string, has no notion of a `.default()` *value*, and (being JSON)
+      #   cannot express a Ruby-side type name at all. Those still need
+      #   `ContentConfigConverter`'s read of the TypeScript.
+      #
+      # So `ImportAstroGenerator` always parses `content.config.ts` (it is
+      # the only source for the Astro-specific helpers and defaults), and
+      # additionally reads this file, when present, to correct
+      # required-ness and refine `z.number()` into `:integer`/`:float`. See
+      # `ImportAstroGenerator#refine_with_json_schema!`.
+      module AstroSchemaJson
+        module_function
+
+        # @param astro_root [String]
+        # @param collection_name [String]
+        # @return [Hash, nil] the parsed `properties`/`required` shape, or
+        #   nil if Astro never generated one for this collection.
+        def read(astro_root, collection_name)
+          path = File.join(astro_root, ".astro/collections/#{collection_name}.schema.json")
+          return nil unless File.file?(path)
+
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          nil
+        end
+
+        # @param schema_json [Hash] as returned by `read`.
+        # @param field_name [String]
+        # @return [Boolean, nil] nil when the field is not described at all
+        #   (the generator then leaves the TS-derived required-ness alone).
+        def required?(schema_json, field_name)
+          return nil unless schema_json.is_a?(Hash)
+
+          properties = schema_json["properties"]
+          return nil unless properties.is_a?(Hash) && properties.key?(field_name)
+
+          Array(schema_json["required"]).include?(field_name)
+        end
+
+        # @return [Symbol, nil] `:integer` or `:float` when the field is a
+        #   JSON Schema number/integer, nil otherwise (including when the
+        #   field is absent) so the generator only ever narrows a `:float`
+        #   guess, never overrides an unrelated type.
+        def numeric_precision(schema_json, field_name)
+          return nil unless schema_json.is_a?(Hash)
+
+          property = (schema_json["properties"] || {})[field_name]
+          return nil unless property.is_a?(Hash)
+
+          case property["type"]
+          when "integer" then :integer
+          when "number" then :float
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/andromeda/import_astro/balanced_scanner.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Andromeda
+  module Generators
+    module ImportAstro
+      # Small bracket-matching helpers shared by ContentConfigConverter and
+      # MdxImportRewriter. `content.config.ts` is TypeScript, but the shapes
+      # this generator needs to recognize (Astro's collection-config shapes)
+      # are a tiny, regular subset of it -- matching parens/braces/brackets
+      # while skipping over string literals is enough to find where a call
+      # or object literal ends, without carrying an actual TS parser around
+      # (the same reasoning `Andromeda::Components::ImportScanner` already
+      # applies to MDX import statements).
+      module BalancedScanner
+        OPEN_TO_CLOSE = { "(" => ")", "{" => "}", "[" => "]" }.freeze
+        QUOTES = ["'", '"', "`"].freeze
+
+        module_function
+
+        # @param source [String]
+        # @param open_index [Integer] index of an opening bracket in `source`.
+        # @return [Integer, nil] the index of its matching closing bracket, or
+        #   nil if `source` ends before one is found (malformed/truncated
+        #   input -- callers treat that the same as "not found").
+        def matching_close(source, open_index)
+          open_char = source[open_index]
+          close_char = OPEN_TO_CLOSE.fetch(open_char)
+          depth = 0
+          i = open_index
+
+          while i < source.length
+            char = source[i]
+
+            if QUOTES.include?(char)
+              i = skip_string(source, i)
+              next
+            elsif char == open_char
+              depth += 1
+            elsif char == close_char
+              depth -= 1
+              return i if depth.zero?
+            end
+
+            i += 1
+          end
+
+          nil
+        end
+
+        # @return [Integer] the index just past the closing quote.
+        def skip_string(source, quote_index)
+          quote = source[quote_index]
+          i = quote_index + 1
+          while i < source.length
+            case source[i]
+            when "\\" then i += 1 # escaped char, skip it too
+            when quote then return i + 1
+            end
+            i += 1
+          end
+          i
+        end
+
+        # Splits `source` (the inside of a `{...}` or `(...)`, braces
+        # excluded) on top-level commas -- i.e. commas that are not nested
+        # inside their own brackets or a string literal. Used both for
+        # `z.object({ ... })` fields and for `z.enum([...])`/`z.array(...)`
+        # argument lists.
+        #
+        # @return [Array<String>] trimmed, non-empty segments (a trailing
+        #   comma produces no empty segment).
+        def split_top_level(source)
+          segments = []
+          depth = 0
+          current = +""
+          i = 0
+
+          while i < source.length
+            char = source[i]
+
+            if QUOTES.include?(char)
+              stop = skip_string(source, i)
+              current << source[i...stop]
+              i = stop
+              next
+            elsif OPEN_TO_CLOSE.key?(char)
+              depth += 1
+            elsif OPEN_TO_CLOSE.value?(char)
+              depth -= 1
+            end
+
+            if char == "," && depth.zero?
+              segments << current
+              current = +""
+            else
+              current << char
+            end
+
+            i += 1
+          end
+          segments << current unless current.strip.empty?
+
+          segments.map(&:strip).reject(&:empty?)
+        end
+
+        # Strips `//line` and `/* block */` comments from `source`,
+        # preserving everything inside string literals untouched. Astro's
+        # own examples comment their schema fields (`// Transform string to
+        # Date object`) -- without this, such a comment would fuse onto the
+        # start of the next field's key when `split_top_level`/
+        # `split_key_value` see it as ordinary text.
+        def strip_comments(source)
+          result = +""
+          i = 0
+
+          while i < source.length
+            char = source[i]
+
+            if QUOTES.include?(char)
+              stop = skip_string(source, i)
+              result << source[i...stop]
+              i = stop
+            elsif source[i, 2] == "//"
+              i = (source.index("\n", i) || source.length)
+            elsif source[i, 2] == "/*"
+              close = source.index("*/", i + 2)
+              i = close ? close + 2 : source.length
+            else
+              result << char
+              i += 1
+            end
+          end
+
+          result
+        end
+
+        # Splits `field: expression` on the first top-level colon -- the key
+        # is always a bare identifier or a quoted string, never containing
+        # brackets, so the first depth-0 colon is unambiguous.
+        #
+        # @return [Array(String, String), nil] `[key, expression]`, or nil if
+        #   no top-level colon is found at all.
+        def split_key_value(source)
+          depth = 0
+          i = 0
+          while i < source.length
+            char = source[i]
+
+            if QUOTES.include?(char)
+              i = skip_string(source, i)
+              next
+            elsif OPEN_TO_CLOSE.key?(char)
+              depth += 1
+            elsif OPEN_TO_CLOSE.value?(char)
+              depth -= 1
+            elsif char == ":" && depth.zero?
+              key = source[0...i].strip.gsub(/\A(['"])(.*)\1\z/, '\2')
+              return [key, source[(i + 1)..].strip]
+            end
+
+            i += 1
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/generators/andromeda/import_astro/content_config_converter.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require_relative "balanced_scanner"
+
+module Andromeda
+  module Generators
+    module ImportAstro
+      # Turns an Astro `src/content.config.ts` into the data
+      # `ImportAstroGenerator` needs to write one `Andromeda::Entry` subclass
+      # per collection.
+      #
+      # This is a static-analysis converter, not a TypeScript parser: Astro's
+      # own collection config is always one of a handful of call shapes
+      # (`defineCollection({ loader: glob({...}), schema: z.object({...}) })`,
+      # optionally with `schema: ({ image }) => z.object({...})`), so a
+      # regex + bracket-matching pass over the source text is enough to find
+      # them, the same trade-off `Andromeda::Components::ImportScanner`
+      # already makes for MDX import statements. Anything shaped differently
+      # falls through to `Attribute#unsupported?` rather than guessing.
+      module ContentConfigConverter
+        Collection = Struct.new(:name, :base, :pattern, :attributes, keyword_init: true)
+
+        # One frontmatter field. `ruby_type` is nil when the Zod expression
+        # could not be recognized at all -- `source` (the original
+        # expression text) is always kept so the generator can turn it into
+        # a TODO comment naming exactly what needs a human (per the
+        # generator's "never a silent omission" requirement).
+        Attribute = Struct.new(
+          :name, :ruby_type, :required, :default, :of, :values, :collection, :source, :note,
+          keyword_init: true
+        ) do
+          def unsupported? = ruby_type.nil?
+        end
+
+        # Astro's own base Zod types. Order matters: more specific
+        # patterns (`z.coerce.date()`) must be tried before the more general
+        # ones they could otherwise collide with in a naive match.
+        SCALAR_PATTERNS = [
+          [/\Az\.string\(\)\z/, :string],
+          [/\Az\.number\(\)\z/, :float],
+          [/\Az\.boolean\(\)\z/, :boolean],
+          [/\Az\.coerce\.date\(\)\z/, :date],
+          [/\Az\.date\(\)\z/, :date]
+        ].freeze
+
+        DEFAULT_LITERAL_RE = /\A(?:true|false|-?\d+(?:\.\d+)?|'[^']*'|"[^"]*"|\[[^\]]*\])\z/.freeze
+
+        module_function
+
+        # @param source [String] the full `content.config.ts` contents.
+        # @param astro_root [String] absolute path to the Astro project, used
+        #   to resolve a `loader: glob({ base: ... })` path.
+        # @return [Array<Collection>]
+        def parse(source, astro_root:)
+          source.scan(/const\s+(\w+)\s*=\s*defineCollection\s*\(/).flatten.map do |const_name|
+            open = source.index("defineCollection", source.index("const #{const_name}"))
+            paren = source.index("(", open)
+            close = BalancedScanner.matching_close(source, paren)
+            body = source[(paren + 1)...close]
+
+            build_collection(const_name, body, astro_root: astro_root)
+          end
+        end
+
+        def build_collection(name, body, astro_root:)
+          body = BalancedScanner.strip_comments(body)
+          base = extract_string(body, /base\s*:/) || "./src/content/#{name}"
+          pattern = extract_string(body, /pattern\s*:/) || "**/*.{md,mdx}"
+
+          Collection.new(
+            name: name,
+            base: File.expand_path(base, astro_root),
+            pattern: pattern,
+            attributes: extract_attributes(body)
+          )
+        end
+
+        # @return [String, nil] the quoted value right after `label_re`, e.g.
+        #   `base: './src/content/blog'` -> `"./src/content/blog"`.
+        def extract_string(body, label_re)
+          match = /#{label_re}\s*(['"])(.*?)\1/.match(body)
+          match && match[2]
+        end
+
+        def extract_attributes(body)
+          object_open = find_schema_object(body)
+          return [] unless object_open
+
+          close = BalancedScanner.matching_close(body, object_open)
+          fields_source = body[(object_open + 1)...close]
+
+          BalancedScanner.split_top_level(fields_source).filter_map do |field|
+            key, expr = BalancedScanner.split_key_value(field)
+            next if key.nil?
+
+            build_attribute(key, expr)
+          end
+        end
+
+        # Finds the `{` of `z.object({ ... })`, whether the schema is given
+        # directly (`schema: z.object({...})`) or behind the `({ image }) =>`
+        # helper form Astro's own examples use for `image()` fields.
+        def find_schema_object(body)
+          match = /schema\s*:.*?z\.object\s*\(\s*\{/m.match(body)
+          return nil unless match
+
+          match.end(0) - 1
+        end
+
+        def build_attribute(key, expr)
+          expr, required, default = strip_modifiers(expr)
+          type, extra = classify(expr)
+
+          Attribute.new(
+            name: key, ruby_type: type, required: type.nil? ? false : required, default: default,
+            of: extra[:of], values: extra[:values], collection: extra[:collection],
+            source: expr, note: extra[:note]
+          )
+        end
+
+        # Repeatedly peels `.optional()`/`z.optional(...)`/`.default(...)`
+        # wrappers off the outside of `expr` until none remain, tracking
+        # whether the field ended up optional and what its default literal
+        # is (Astro/Zod semantics: `.optional()` and `.default()` both make
+        # a field non-required; only `.default()` also supplies a value).
+        def strip_modifiers(expr)
+          required = true
+          default = nil
+
+          loop do
+            if expr.end_with?(".optional()")
+              expr = expr[0...-".optional()".length].strip
+              required = false
+            elsif (inner = unwrap_call(expr, "z.optional"))
+              expr = inner.strip
+              required = false
+            elsif (inner = suffix_call_argument(expr, ".default"))
+              default = literal_default(inner)
+              expr = expr[0...-(".default(#{inner})".length)].strip
+              required = false
+            else
+              break
+            end
+          end
+
+          [expr, required, default]
+        end
+
+        # @return [String, nil] the argument text of a trailing `.method(...)`
+        #   call, if `expr` ends with exactly that call.
+        def suffix_call_argument(expr, method_name)
+          marker = "#{method_name}("
+          index = expr.rindex(marker)
+          return nil unless index
+
+          close = BalancedScanner.matching_close(expr, index + method_name.length)
+          return nil unless close == expr.length - 1
+
+          expr[(index + marker.length)...close]
+        end
+
+        # @return [String, nil] the argument text of `prefix(...)` when
+        #   `expr` is exactly that call (not just contains it).
+        def unwrap_call(expr, prefix)
+          marker = "#{prefix}("
+          return nil unless expr.start_with?(marker)
+
+          close = BalancedScanner.matching_close(expr, prefix.length)
+          return nil unless close == expr.length - 1
+
+          expr[(prefix.length + 1)...close]
+        end
+
+        # Only a recognizable Ruby-literal-compatible default is carried
+        # over verbatim (JS and Ruby agree on `true`/`false`/numbers/quoted
+        # strings/arrays-of-those); anything else is dropped and the field
+        # falls back to being flagged unsupported by `classify` seeing an
+        # expression it was not built to trust the shape of.
+        def literal_default(text)
+          text.strip.match?(DEFAULT_LITERAL_RE) ? text.strip : nil
+        end
+
+        # @return [Array(Symbol, Hash), Array(nil, Hash)] the Ruby attribute
+        #   type (nil if unrecognized) and any type-specific extras
+        #   (`of:`/`values:`/`collection:`/`note:`).
+        def classify(expr)
+          SCALAR_PATTERNS.each do |pattern, type|
+            return [type, {}] if pattern.match?(expr)
+          end
+
+          if (inner = unwrap_call(expr, "z.enum"))
+            return classify_enum(inner)
+          end
+
+          if (inner = unwrap_call(expr, "z.array"))
+            return classify_array(inner)
+          end
+
+          return [:image, {}] if expr == "image()"
+
+          if (match = /\Areference\(\s*(['"])(.*?)\1\s*\)\z/.match(expr))
+            return [:reference, { collection: match[2].to_sym }]
+          end
+
+          [nil, {}]
+        end
+
+        def classify_enum(inner)
+          bracket_match = /\A\[(.*)\]\z/m.match(inner.strip)
+          return [nil, {}] unless bracket_match
+
+          values = BalancedScanner.split_top_level(bracket_match[1]).map do |literal|
+            literal.strip.gsub(/\A(['"])(.*)\1\z/, '\2')
+          end
+          [:enum, { values: values }]
+        end
+
+        # `of:` only carries over for a scalar element type Andromeda's own
+        # Schema supports for arrays (03-6) -- an array of something more
+        # exotic (`z.array(z.object({...}))`) is left with `of: nil` and a
+        # note, so the generator's TODO explains exactly why rather than
+        # silently guessing.
+        def classify_array(inner)
+          element_type, = classify(inner.strip)
+          return [:array, { of: element_type }] if element_type
+
+          [:array, { of: nil, note: "array element type `#{inner.strip}` is not a supported scalar" }]
+        end
+      end
+    end
+  end
+end