andromeda_cms 0.1.0-aarch64-linux

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

@@ -0,0 +1,313 @@
+# frozen_string_literal: true
+
+require "andromeda_cms"
+require "active_support/core_ext/string/inflections"
+require_relative "content_config_converter"
+require_relative "astro_schema_json"
+require_relative "mdx_import_rewriter"
+require_relative "mdx_content_scanner"
+require_relative "../component/component_generator"
+
+module Andromeda
+  module Generators
+    # `rails g andromeda:import_astro PATH_TO_ASTRO_PROJECT [--dry-run]`
+    # -- one-shot migration of an existing Astro
+    # project's content into a host app already set up with
+    # `andromeda:install`:
+    #
+    #   1. Copy every collection's content directory into `app/content/
+    #      <collection>/`, and `src/assets` into `app/assets/`, rewriting
+    #      only frontmatter keys and MDX
+    #      import statements -- otherwise byte-for-byte.
+    #   2. Convert `src/content.config.ts` into one `Andromeda::Entry`
+    #      subclass per collection, mapping the Zod shapes
+    #      Astro supports; anything else becomes a commented-out line with a
+    #      TODO rather than a silent omission.
+    #   3. Generate a partial stub for every MDX component tag that has no
+    #      partial yet.
+    #   4. Print a migration report: what was copied/rewritten/generated,
+    #      and everything that still needs a human.
+    #
+    # `--dry-run` runs the exact same analysis and prints the same report,
+    # but writes nothing -- implemented as Thor's own `--pretend`, which
+    # every `create_file`/`copy_file` call below already respects, rather
+    # than a second no-op code path to keep in sync with the real one.
+    class ImportAstroGenerator < Rails::Generators::Base
+      argument :astro_path, type: :string, banner: "PATH_TO_ASTRO_PROJECT"
+      class_option :dry_run, type: :boolean, default: false,
+                              desc: "Print the migration report without writing any files"
+
+      def import
+        # Thor's own options Hash is frozen by the time a command runs, so
+        # `--dry-run` is translated into Thor's built-in `--pretend`
+        # (which every `create_file`/`copy_file` call below already
+        # respects) via a fresh, unfrozen Hash rather than an in-place
+        # mutation.
+        self.options = options.merge(pretend: true) if options[:dry_run]
+
+        @report = {
+          copied: [], frontmatter_renames: [], import_rewrites: [],
+          models: [], stubs: [], unsupported_schema: [], unsupported_expressions: [],
+          schema_json_used: [], notes: []
+        }
+
+        load_collections
+        copy_collections
+        copy_assets
+        generate_entry_classes
+        generate_component_stubs
+        print_report
+      end
+
+      private
+
+      def astro_root
+        @astro_root ||= File.expand_path(astro_path)
+      end
+
+      def config_path
+        File.join(astro_root, "src/content.config.ts")
+      end
+
+      # @return [Array<ImportAstro::ContentConfigConverter::Collection>]
+      def load_collections
+        @collections =
+          if File.file?(config_path)
+            ImportAstro::ContentConfigConverter.parse(File.read(config_path), astro_root: astro_root)
+          else
+            @report[:notes] << "no src/content.config.ts found -- falling back to every directory under " \
+                                "src/content/ with no schema"
+            fallback_collections
+          end
+
+        @collections.each { |collection| refine_with_json_schema!(collection) }
+      end
+
+      # The fallback clause: every top-level directory under
+      # `src/content/` becomes a schema-less collection so the content
+      # itself is still migrated even without a `content.config.ts`.
+      def fallback_collections
+        base = File.join(astro_root, "src/content")
+        return [] unless Dir.exist?(base)
+
+        Dir.children(base).select { |name| File.directory?(File.join(base, name)) }.sort.map do |name|
+          ImportAstro::ContentConfigConverter::Collection.new(
+            name: name, base: File.join(base, name), pattern: "**/*.{md,mdx}", attributes: []
+          )
+        end
+      end
+
+      # Prefers the generated JSON Schema -- see astro_schema_json.rb
+      # for exactly what it can and cannot correct.
+      def refine_with_json_schema!(collection)
+        schema_json = ImportAstro::AstroSchemaJson.read(astro_root, collection.name)
+        return unless schema_json
+
+        @report[:schema_json_used] << collection.name
+        collection.attributes.each do |attr|
+          required = ImportAstro::AstroSchemaJson.required?(schema_json, attr.name)
+          attr.required = required unless required.nil?
+
+          next unless attr.ruby_type == :float
+
+          precision = ImportAstro::AstroSchemaJson.numeric_precision(schema_json, attr.name)
+          attr.ruby_type = precision if precision
+        end
+      end
+
+      def copy_collections
+        @collections.each do |collection|
+          next unless Dir.exist?(collection.base)
+
+          Dir.glob(File.join(collection.base, "**/*")).sort.each do |src|
+            next unless File.file?(src)
+
+            relative = src.delete_prefix("#{collection.base}/")
+            dest = "app/content/#{collection.name}/#{relative}"
+            copy_content_file(src, dest)
+          end
+        end
+      end
+
+      # Byte-for-byte except for the two rewrites below, and
+      # only for `.md`/`.mdx` files -- a sibling image living inside a
+      # directory-form entry (`my-post/cover.png`) is copied untouched.
+      def copy_content_file(src, dest)
+        extension = File.extname(src).downcase
+        unless %w[.md .mdx].include?(extension)
+          create_file dest, File.binread(src)
+          @report[:copied] << dest
+          return
+        end
+
+        source = File.read(src)
+        fixed, renames = Andromeda::Fix.fix_source(source)
+        renames.each { |from, to| @report[:frontmatter_renames] << "#{dest}: #{from} -> #{to}" }
+
+        if extension == ".mdx"
+          fixed, rewrites = ImportAstro::MdxImportRewriter.rewrite(fixed)
+          rewrites.each { |r| @report[:import_rewrites] << "#{dest}: #{r[:from]} -> #{r[:to]}" }
+        end
+
+        create_file dest, fixed
+        @report[:copied] << dest
+
+        scan_mdx_content(fixed, dest) if extension == ".mdx"
+      end
+
+      def scan_mdx_content(source, dest)
+        (@component_usages ||= {}).merge!(
+          ImportAstro::MdxContentScanner.component_usages(source, path: dest)
+        ) { |_name, existing, incoming| existing.props |= incoming.props; existing }
+
+        @report[:unsupported_expressions].concat(
+          ImportAstro::MdxContentScanner.unsupported_expressions(source, path: dest)
+        )
+      end
+
+      def copy_assets
+        assets_root = File.join(astro_root, "src/assets")
+        return unless Dir.exist?(assets_root)
+
+        Dir.glob(File.join(assets_root, "**/*")).sort.each do |src|
+          next unless File.file?(src)
+
+          relative = src.delete_prefix("#{assets_root}/")
+          dest = "app/assets/#{relative}"
+          create_file dest, File.binread(src)
+          @report[:copied] << dest
+        end
+      end
+
+      def generate_entry_classes
+        @collections.each do |collection|
+          path = model_path(collection)
+          create_file path, model_content(collection)
+          @report[:models] << path
+
+          collection.attributes.select(&:unsupported?).each do |attr|
+            @report[:unsupported_schema] << "#{collection.name}.#{attr.name} (content.config.ts: #{attr.source})"
+          end
+        end
+      end
+
+      def generate_component_stubs
+        return unless @component_usages
+
+        @component_usages.each_value do |usage|
+          next if partial_exists?(usage.name)
+
+          # Reuses the real `andromeda:component` generator (rather than
+          # duplicating its stub-content logic here) via Thor's own
+          # `invoke`, which shares this generator's `destination_root`
+          # automatically. `pretend:` is passed through explicitly --
+          # `invoke` only inherits a fresh invocation's *original* options
+          # (captured at construction time), not this instance's later
+          # `self.options = options.merge(pretend: true)` translation of
+          # `--dry-run` above.
+          invoke Andromeda::Generators::ComponentGenerator, [usage.name, *usage.props], pretend: options[:dry_run]
+          @report[:stubs] << component_partial_path(usage.name)
+        end
+      end
+
+      def partial_exists?(name)
+        File.exist?(File.join(destination_root, component_partial_path(name)))
+      end
+
+      def component_partial_path(name)
+        "#{Andromeda.config.components_path}/_#{Andromeda::Components.underscore(name)}.html.erb"
+      end
+
+      def namespace_modules
+        @namespace_modules ||= Andromeda.config.entry_namespace.split("::")
+      end
+
+      def model_path(collection)
+        File.join(Andromeda.config.entry_class_path, "#{collection.name.to_s.singularize}.rb")
+      end
+
+      def model_content(collection)
+        indent = "  " * namespace_modules.size
+        lines = ["# frozen_string_literal: true", ""]
+        namespace_modules.each_with_index { |mod, i| lines << "#{"  " * i}module #{mod}" }
+        lines << "#{indent}class #{collection.name.to_s.singularize.camelize} < Andromeda::Entry"
+        lines << "#{indent}  collection :#{collection.name}, base: \"app/content/#{collection.name}\", " \
+                 "pattern: \"#{collection.pattern}\""
+
+        unless collection.attributes.empty?
+          lines << ""
+          collection.attributes.each { |attr| attribute_lines(attr).each { |line| lines << "#{indent}  #{line}" } }
+        end
+
+        lines << "#{indent}end"
+        namespace_modules.size.downto(1) { |i| lines << "#{"  " * (i - 1)}end" }
+        "#{lines.join("\n")}\n"
+      end
+
+      # @return [Array<String>] one or more lines for this attribute: a
+      #   real `attribute` declaration, or -- when the Zod expression could
+      #   not be mapped -- a `# TODO` naming the original source plus a
+      #   commented-out best guess, never a silent omission.
+      def attribute_lines(attr)
+        return unsupported_attribute_lines(attr) if attr.unsupported?
+
+        lines = []
+        lines << "# NOTE: #{attr.note}" if attr.note
+        lines << "attribute :#{snake_name(attr)}, :#{attr.ruby_type}#{attribute_modifiers(attr)}"
+        lines
+      end
+
+      def unsupported_attribute_lines(attr)
+        [
+          "# TODO: unsupported schema for `#{attr.name}` in content.config.ts (#{attr.source}) -- " \
+          "add the equivalent `attribute` by hand.",
+          "# attribute :#{snake_name(attr)}, :string"
+        ]
+      end
+
+      # The generated class's `attribute` calls must use the same
+      # snake_case names `Andromeda::Fix` gives the frontmatter keys
+      # themselves -- `pubDate` in `content.config.ts` has to line
+      # up with `pub_date:` in the copied Markdown, or the schema would
+      # look for a key that no longer exists in the file.
+      def snake_name(attr)
+        Andromeda::Fix.snake_case(attr.name)
+      end
+
+      def attribute_modifiers(attr)
+        parts = []
+        parts << "of: :#{attr.of}" if attr.ruby_type == :array && attr.of
+        parts << "values: #{attr.values.inspect}" if attr.ruby_type == :enum
+        parts << "collection: :#{attr.collection}" if attr.ruby_type == :reference
+        parts << "required: true" if attr.required && attr.default.nil?
+        parts << "default: #{attr.default}" if attr.default
+        parts.empty? ? "" : ", #{parts.join(", ")}"
+      end
+
+      def print_report
+        say ""
+        say(options[:dry_run] ? "Astro import (dry run -- nothing was written):" : "Astro import complete:")
+        say ""
+        report_section "Copied", @report[:copied]
+        report_section "Frontmatter keys renamed to snake_case", @report[:frontmatter_renames]
+        report_section "MDX import statements rewritten", @report[:import_rewrites]
+        report_section "Entry classes generated", @report[:models]
+        report_section "Component stubs generated", @report[:stubs]
+        report_section "Collections that used Astro's generated JSON Schema", @report[:schema_json_used]
+        say ""
+        say "Needs a human:"
+        report_section "  Unmapped schema fields", @report[:unsupported_schema], indent: "    "
+        report_section "  Expressions the renderer cannot evaluate", @report[:unsupported_expressions], indent: "    "
+        report_section "  Notes", @report[:notes], indent: "    "
+      end
+
+      def report_section(title, items, indent: "  ")
+        return if items.empty?
+
+        say "#{title}:"
+        items.each { |item| say "#{indent}#{item}" }
+        say ""
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../../andromeda/components/static_expression"
+
+module Andromeda
+  module Generators
+    module ImportAstro
+      # Parses an already-copied `.mdx` file with the real Sätteri-backed
+      # `Andromeda::Parser` (rather than a second regex pass) to find:
+      #
+      # - every JSX component tag actually used, with the prop names seen on
+      #   it (for generating partial stubs), and
+      # - every `{...}` expression that `Andromeda::Components::
+      #   StaticExpression` -- the same evaluator the real renderer uses --
+      #   cannot evaluate, for the migration report's "expressions the
+      #   renderer cannot evaluate" section.
+      #
+      # This only inspects the tree; it never renders anything, so it needs
+      # no view layer and works the same whether or not the host app has
+      # partials yet.
+      module MdxContentScanner
+        ComponentUsage = Struct.new(:name, :props, keyword_init: true)
+
+        module_function
+
+        # @param source [String] MDX source, already import-rewritten (the
+        #   rewrite does not change tag usage, so scan order does not
+        #   matter).
+        # @param path [String] for error messages only.
+        # @return [Hash{String => ComponentUsage}] tag name -> usage,
+        #   `Fragment` excluded (never a real component).
+        def component_usages(source, path:)
+          tree = Andromeda::Parser.parse(source, mdx: true, path: path)
+          usages = {}
+
+          walk(tree) do |node|
+            next unless %w[mdxJsxFlowElement mdxJsxTextElement].include?(node[:type])
+
+            name = node[:name]
+            next if name.nil? || name == "Fragment" || name.include?(".")
+
+            usage = (usages[name] ||= ComponentUsage.new(name: name, props: []))
+            (node[:attributes] || []).each do |attribute|
+              next unless attribute[:type] == "mdxJsxAttribute"
+
+              usage.props << attribute[:name] unless usage.props.include?(attribute[:name])
+            end
+          end
+
+          usages
+        rescue Andromeda::SyntaxError, Andromeda::ParserError
+          # Not this generator's job to diagnose a broken source file --
+          # `andromeda:check`/the renderer will raise the same error again,
+          # with the same message, once the file is actually rendered. The
+          # migration report calls this out instead of failing the import.
+          {}
+        end
+
+        # @return [Array<String>] one line per expression the renderer would
+        #   raise on, `"path:line: {source}"`.
+        def unsupported_expressions(source, path:)
+          tree = Andromeda::Parser.parse(source, mdx: true, path: path)
+          problems = []
+
+          walk(tree) do |node|
+            next unless %w[mdxFlowExpression mdxTextExpression].include?(node[:type])
+
+            begin
+              Andromeda::Components::StaticExpression.evaluate(node[:value].to_s, frontmatter: {})
+            rescue Andromeda::Components::StaticExpression::UnsupportedExpressionError
+              line = node.dig(:position, :start, :line)
+              problems << "#{path}:#{line}: {#{node[:value]}}"
+            end
+          end
+
+          problems
+        rescue Andromeda::SyntaxError, Andromeda::ParserError
+          []
+        end
+
+        def walk(node, &block)
+          return unless node.is_a?(Hash)
+
+          yield node if node[:type]
+          (node[:children] || []).each { |child| walk(child, &block) }
+        end
+        private_class_method :walk
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Andromeda
+  module Generators
+    module ImportAstro
+      # Rewrites MDX import statements to the partial-path form:
+      # `import Callout from '../../components/Callout.astro';`
+      # becomes `import Callout from 'content_components/callout';`. Only
+      # component imports are rewritten -- an image import
+      # (`import cover from './cover.png'`) is left alone, since `cover` is
+      # bound to an asset, not resolved as a JSX tag (image imports are a
+      # separate, deferred concern from this rewrite).
+      #
+      # A regex pass over the raw text, matching
+      # `Andromeda::Components::ImportScanner`'s own reasoning: MDX imports
+      # are a small, regular subset of ES module syntax, and rewriting only
+      # ever needs to look at one import statement at a time.
+      module MdxImportRewriter
+        DEFAULT_IMPORT_RE = /^import\s+([A-Za-z_$][\w$]*)\s+from\s+(['"])(.*?)\2\s*;?[ \t]*$/
+        NAMED_IMPORT_RE = /^import\s*\{([^}]*)\}\s*from\s+(['"])(.*?)\2\s*;?[ \t]*$/
+        NAMED_BINDING_RE = /\A([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?\z/
+        IMAGE_EXTENSIONS = %w[.png .jpg .jpeg .gif .svg .webp .avif].freeze
+
+        module_function
+
+        # @param source [String] a whole `.mdx` file's contents.
+        # @return [Array(String, Array<Hash>)] the rewritten source and a
+        #   list of `{from:, to:}` rewrites applied, for the migration
+        #   report.
+        def rewrite(source)
+          rewrites = []
+
+          rewritten = source.gsub(NAMED_IMPORT_RE) do |whole|
+            rewrite_named(whole, Regexp.last_match(1), Regexp.last_match(3), rewrites)
+          end
+
+          rewritten = rewritten.gsub(DEFAULT_IMPORT_RE) do |whole|
+            rewrite_default(whole, Regexp.last_match(1), Regexp.last_match(3), rewrites)
+          end
+
+          [rewritten, rewrites]
+        end
+
+        def rewrite_default(whole, name, path, rewrites)
+          return whole unless component_name?(name) && !image_path?(path)
+
+          replacement = "import #{name} from '#{partial_path(name)}';"
+          rewrites << { from: whole.strip, to: replacement }
+          replacement
+        end
+
+        # A named import list is rewritten only when every binding looks
+        # like a component (capitalized) -- one import path cannot honestly
+        # become several different partial paths, and a mixed list
+        # (components alongside a lowercase helper) is rare enough in
+        # practice that leaving it untouched (and letting naming-convention
+        # resolution handle the components at render time) is safer than
+        # guessing which names to split out.
+        def rewrite_named(whole, bindings_source, _path, rewrites)
+          bindings = bindings_source.split(",").filter_map { |b| b.strip unless b.strip.empty? }
+          locals = bindings.map { |binding| NAMED_BINDING_RE.match(binding) }
+          return whole if locals.any?(&:nil?)
+
+          local_names = locals.map { |m| m[2] || m[1] }
+          return whole unless local_names.all? { |name| component_name?(name) }
+
+          replacement = local_names.map { |name| "import #{name} from '#{partial_path(name)}';" }.join("\n")
+          rewrites << { from: whole.strip, to: replacement }
+          replacement
+        end
+
+        def component_name?(name)
+          name.match?(/\A[A-Z]/)
+        end
+
+        def image_path?(path)
+          IMAGE_EXTENSIONS.include?(File.extname(path).downcase)
+        end
+
+        # @return [String] `content_components/<underscored name>`, matching
+        #   the naming-convention `Andromeda::Components` already resolves
+        #   tags with, minus the `app/views/` prefix a partial
+        #   path never includes.
+        def partial_path(name)
+          base = Andromeda.config.components_path.sub(%r{\Aapp/views/}, "")
+          "#{base}/#{Andromeda::Components.underscore(name)}"
+        end
+      end
+    end
+  end
+end

data/lib/generators/andromeda/install/USAGE

@@ -0,0 +1,11 @@
+Description:
+    Sets up a host application for Andromeda: creates app/content/ and
+    app/views/content_components/, writes a commented config/initializers/
+    andromeda.rb, and appends the paths Andromeda writes at build time
+    (/.andromeda/ and /app/assets/builds/andromeda/) to .gitignore and
+    .dockerignore.
+
+    Safe to run more than once: it never duplicates a line it already added.
+
+Example:
+    rails generate andromeda:install

data/lib/generators/andromeda/install/install_generator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "andromeda_cms"
+
+module Andromeda
+  module Generators
+    # `rails g andromeda:install` -- one-time setup for a host
+    # application: the content directory, the component partials directory,
+    # a commented initializer, and the two ignore files expect
+    # `.andromeda/` (the conversion cache) and the copied-image build
+    # directory to be excluded from.
+    #
+    # Every step here is safe to run twice: directories/files Thor already
+    # knows about follow its normal conflict handling, and the ignore-file
+    # lines are only appended when they are not already present.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      IGNORE_LINES = ["/.andromeda/", "/app/assets/builds/andromeda/"].freeze
+
+      def create_content_directory
+        empty_directory "app/content"
+        create_file "app/content/.keep"
+      end
+
+      def create_components_directory
+        path = Andromeda.config.components_path
+        empty_directory path
+        create_file "#{path}/.keep"
+      end
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/andromeda.rb"
+      end
+
+      def update_ignore_files
+        [".gitignore", ".dockerignore"].each { |filename| append_ignore_lines(filename) }
+      end
+
+      def show_next_steps
+        say ""
+        say "Andromeda is set up. Next steps:"
+        say ""
+        say "  1. Generate a collection:"
+        say "       rails generate andromeda:collection posts title:string pub_date:date"
+        say ""
+        say "  2. Or import existing content from an Astro project:"
+        say "       rails generate andromeda:import_astro path/to/astro-project"
+        say ""
+      end
+
+      private
+
+      # Appends whichever of IGNORE_LINES aren't already in `filename`, or
+      # explains why nothing happened when the file doesn't exist -- an
+      # app without Docker, for instance, has no .dockerignore and should
+      # not get one invented for it.
+      def append_ignore_lines(filename)
+        path = File.join(destination_root, filename)
+
+        unless File.exist?(path)
+          say_status :skip, "#{filename} not found -- if you add one later, also add: #{IGNORE_LINES.join(", ")}", :yellow
+          return
+        end
+
+        existing_lines = File.readlines(path, chomp: true)
+        missing = IGNORE_LINES.reject { |line| existing_lines.include?(line) }
+        if missing.empty?
+          say_status :identical, filename, :blue
+          return
+        end
+
+        append_to_file filename, "#{missing.join("\n")}\n"
+      end
+    end
+  end
+end

data/lib/generators/andromeda/install/templates/initializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Uncomment and edit any of these to override Andromeda's defaults -- see
+# Andromeda::Configuration for the full description of each setting.
+Andromeda.configure do |config|
+  # Where content files live, relative to the application root.
+  # config.content_path = "app/content"
+
+  # Namespace of the entry classes -- `Content::Post` lives at
+  # app/models/content/post.rb by default. Change this if your app already
+  # defines a top-level `Content`.
+  # config.entry_namespace = "Content"
+
+  # Directory holding the partials MDX components resolve to.
+  # config.components_path = "app/views/content_components"
+
+  # Where `andromeda:build` writes converted content. Hidden and ignored by
+  # git and Docker, like Astro's own .astro/.
+  # config.build_path = ".andromeda"
+
+  # Rouge theme used for code blocks; the default mirrors the Shiki theme
+  # Astro ships with.
+  # config.highlight_theme = "github.dark"
+
+  # :development (convert on demand, checking each source file's digest) or
+  # :production (read-only; raises Andromeda::BuildMissing if
+  # `andromeda:build` never ran). The Railtie sets this from Rails.env at
+  # boot, so overriding it here is rarely needed.
+  # config.mode = :development
+end