andromeda_cms 0.1.0-aarch64-linux

data/lib/andromeda/entry.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Andromeda
+  # The base class users subclass to define a collection:
+  #
+  #   class Content::Post < Andromeda::Entry
+  #     collection :blog, base: "app/content/blog", pattern: "**/*.{md,mdx}"
+  #
+  #     attribute :title,    :string, required: true
+  #     attribute :pub_date, :date,   required: true
+  #     attribute :draft,    :boolean, default: false
+  #
+  #     scope :published, -> { where(draft: false) }
+  #   end
+  #
+  #   Content::Post.published.order(pub_date: :desc).limit(10)
+  #   Content::Post.find("hello-world")   # => Content::Post
+  #   Content::Post.find("nope")          # => raises Andromeda::EntryNotFound
+  #
+  # `Entry` only holds source-derived data (`id`/`collection`/`data`/`body`/
+  # `file_path`/`digest`) -- it does not render HTML. Rendering is the
+  # renderer's job and the store's; this class exists so
+  # they have something to render/persist in the first place.
+  class Entry
+    class << self
+      # @return [Symbol, nil] set by `collection`.
+      attr_reader :collection_name
+      # @return [String, nil] absolute path, set by `collection`.
+      attr_reader :base_dir
+      # @return [String, nil] a Dir.glob pattern relative to `base_dir`.
+      attr_reader :pattern
+
+      # Declares this class as the entry type for `name`, registering it in
+      # Andromeda::Registry so `Andromeda.get_collection`/`get_entry`
+      # and `reference` resolution can find it by name.
+      #
+      # @param name [Symbol, String]
+      # @param base [String] absolute, or relative to Rails.root (or the
+      #   current working directory outside Rails).
+      # @param pattern [String] a Dir.glob pattern, relative to `base`.
+      def collection(name, base:, pattern: "**/*.{md,mdx}")
+        @collection_name = name.to_sym
+        @base_dir = resolve_base(base)
+        @pattern = pattern
+        @entries = nil
+        Andromeda::Registry.register(@collection_name, self)
+        self
+      end
+
+      # Declares one frontmatter attribute, delegating all type/validation
+      # logic to Andromeda::Schema (this class never reimplements it) and
+      # additionally defining an instance reader so `post.title` works as
+      # a shorthand for `post.data[:title]`.
+      #
+      # A `:reference` attribute gets a different reader: it resolves the
+      # stored `Andromeda::Reference` to the actual target entry (lazily,
+      # via the registry) rather than returning the pointer itself --
+      # `post.data[:author]` still holds the raw Reference for callers that
+      # want it.
+      #
+      # @see Andromeda::Schema#attribute for the full parameter list.
+      def attribute(name, type, **options)
+        schema.attribute(name, type, **options)
+        attr_name = name.to_sym
+
+        if type == :reference
+          define_method(attr_name) { resolve_reference(attr_name) }
+        else
+          define_method(attr_name) { data[attr_name] }
+        end
+
+        self
+      end
+
+      # `scope :published, -> { where(draft: false) }`. The block runs via
+      # `instance_exec` against an Andromeda::Relation (either `all`, at the
+      # class level, or an existing Relation when chained), so it can call
+      # `where`/`order`/other scopes unqualified.
+      #
+      # @param name [Symbol]
+      # @param callable [Proc]
+      def scope(name, callable)
+        name = name.to_sym
+        scopes[name] = callable
+        define_singleton_method(name) { |*args| all.public_send(name, *args) }
+        self
+      end
+
+      # @return [Hash{Symbol => Proc}] public so Andromeda::Relation can look
+      #   up a scope by name when one is chained off a Relation instance.
+      def scopes
+        @scopes ||= {}
+      end
+
+      # @return [Andromeda::Schema] this class's own, never inherited/shared
+      #   -- each subclass declares its own attributes independently.
+      def schema
+        @schema ||= Andromeda::Schema.new
+      end
+
+      # @return [Andromeda::Relation] every loaded entry.
+      def all
+        Andromeda::Relation.new(entries, entry_class: self)
+      end
+
+      # @param id [String, Symbol]
+      # @return [Andromeda::Entry]
+      # @raise [Andromeda::EntryNotFound]
+      def find(id)
+        target = id.to_s
+        entries.find { |entry| entry.id == target } ||
+          raise(Andromeda::EntryNotFound.new(collection: collection_name, id: target, candidates: entries.map(&:id)))
+      end
+
+      def find_by(conditions = nil, &block)
+        all.find_by(conditions, &block)
+      end
+
+      def where(conditions = nil, &block)
+        all.where(conditions, &block)
+      end
+
+      def order(*criteria)
+        all.order(*criteria)
+      end
+
+      def limit(count)
+        all.limit(count)
+      end
+
+      def first(count = nil)
+        all.first(count)
+      end
+
+      def count
+        entries.size
+      end
+
+      # The list-view counterpart to `all`: in production
+      # this reads only `.andromeda/<collection>/_index.json` (no source
+      # file, no parsing), the same data an index page needs (`id`/`data`/
+      # `headings`/`digest`/`file_path`) without opening every entry's own
+      # JSON. In development it refreshes stale entries first so
+      # edits show up without a separate build step. Additive: `all`/
+      # `find`/`where`/etc. are unchanged and still read source files
+      # directly through Andromeda::Loader.
+      #
+      # @return [Array<Hash>]
+      # @raise [Andromeda::BuildMissing] in production, if nothing has been
+      #   built for this collection yet.
+      def index
+        Andromeda::Pipeline.new.collection_index(self)
+      end
+
+      # Drops the in-memory cache, forcing the next query to re-run the
+      # Loader. Used by tests that change fixtures mid-example, and is the
+      # hook the dev-mode "reconvert on stale mtime" check will call.
+      def reload!
+        @entries = nil
+      end
+
+      private
+
+      # Production never touches source files: everything a query
+      # needs was validated and written to `_index.json` at build time, so
+      # reading it back is both faster and immune to a content file that
+      # changed on disk after the build. Development goes to the Loader so
+      # edits are visible without a build step.
+      def entries
+        @entries ||= production? ? entries_from_index : load_entries_from_source
+      end
+
+      def production?
+        Andromeda.config.mode == :production
+      end
+
+      def load_entries_from_source
+        Andromeda::Loader.new(
+          entry_class: self, base: base_dir, pattern: pattern, schema: schema
+        ).load
+      end
+
+      # The index carries no body: rendering already happened at build time,
+      # and `Entry#html` reads the per-entry JSON rather than the body, so a
+      # listing never pays for content it does not show.
+      def entries_from_index
+        index.map do |summary|
+          summary = summary.transform_keys(&:to_sym)
+          new(
+            id: summary[:id],
+            collection: collection_name,
+            data: summary[:data],
+            body: nil,
+            file_path: summary[:file_path],
+            digest: summary[:digest]
+          )
+        end
+      end
+
+      # `base:` is written as a project-relative string in every example
+      # (`"app/content/blog"`) so it reads the same in an initializer-free
+      # Rails app either way; resolving it here (rather than deferring to
+      # the Loader) keeps the Loader itself Rails-agnostic and testable with
+      # plain absolute paths.
+      def resolve_base(base)
+        return base if Pathname.new(base).absolute?
+
+        File.join(Andromeda.config.project_root, base)
+      end
+    end
+
+    # @return [String]
+    attr_reader :id
+    # @return [Symbol]
+    attr_reader :collection
+    # @return [Hash] Symbol-keyed validated frontmatter (may also carry
+    #   String keys for unrecognized frontmatter -- see Schema::Result).
+    attr_reader :data
+    # @return [String] raw Markdown/MDX body, frontmatter stripped but with
+    #   original line numbers preserved (Andromeda::Frontmatter#parse).
+    attr_reader :body
+    # @return [String] absolute path to the source file.
+    attr_reader :file_path
+    # @return [String] SHA-256 of the whole source file, for cache keys.
+    attr_reader :digest
+
+    def initialize(id:, collection:, data:, body:, file_path:, digest:)
+      @id = id
+      @collection = collection
+      @data = data
+      @body = body
+      @file_path = file_path
+      @digest = digest
+    end
+
+    # The rendered HTML for `body` (MDX components expanded),
+    # produced and cached by Andromeda::Pipeline rather than here --
+    # this method only decides *when* to ask for it. Memoized on the
+    # instance (not globally): a fresh Entry is what a reload/re-Loader-pass
+    # produces, carrying today's `digest`, so per-instance memoization can
+    # never serve a stale render across a reload the way a class-level or
+    # process-wide cache could (see Configuration#mode's dev-mode note).
+    #
+    # @return [String]
+    # @raise [Andromeda::BuildMissing] in production, if this entry has
+    #   never been built.
+    def html
+      converted[:html]
+    end
+
+    # @return [Array<Hash>] `{depth:, slug:, text:}` per heading, in
+    #   document order (Andromeda::Renderer::Result#headings).
+    # @raise [Andromeda::BuildMissing] in production, if this entry has
+    #   never been built.
+    def headings
+      converted[:headings]
+    end
+
+    # @return [Hash] everything needed to rebuild this entry with `from_h`,
+    #   so the build step can persist it (`.andromeda/<collection>/<id>.json`) and
+    #   restore it later without re-parsing/re-validating the source file.
+    def to_h
+      { id: id, collection: collection, data: data, body: body, file_path: file_path, digest: digest }
+    end
+
+    # @param hash [Hash] as produced by `to_h` (String or Symbol keys).
+    # @return [Andromeda::Entry]
+    def self.from_h(hash)
+      new(**hash.transform_keys(&:to_sym))
+    end
+
+    private
+
+    def converted
+      @converted ||= Andromeda::Pipeline.new.fetch(self)
+    end
+
+    # @param attr_name [Symbol] a `:reference`-typed attribute.
+    # @return [Andromeda::Entry, nil]
+    # @raise [Andromeda::EntryNotFound] naming both the target collection
+    #   and id, via Entry.find on the referenced collection.
+    def resolve_reference(attr_name)
+      reference = data[attr_name]
+      return nil if reference.nil?
+
+      # Only reached when the caller actually asks for `post.author` --
+      # deliberately not resolved (or even looked up) at load time, so
+      # referencing an entry never forces every other collection to load.
+      Andromeda.get_entry(reference.collection, reference.id)
+    end
+  end
+end

data/lib/andromeda/errors.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Andromeda
+  # Base class so host applications can rescue everything this gem raises.
+  class Error < StandardError; end
+
+  # Raised when Markdown or MDX cannot be parsed. Carries the source location so
+  # editors and CI logs can point at the offending line rather than the file.
+  class SyntaxError < Error
+    attr_reader :path, :line, :column, :raw_message
+
+    def initialize(message, path: nil, line: nil, column: nil)
+      @path = path
+      @line = line
+      @column = column
+      # Kept so the error can be rebuilt once the path is known without having
+      # to strip the location back out of the formatted message.
+      @raw_message = message
+      super(location ? "#{location}: #{message}" : message)
+    end
+
+    # Returns a copy of this error attributed to `path`.
+    def at(path)
+      self.class.new(raw_message, path: path, line: line, column: column)
+    end
+
+    def location
+      return nil unless path || line
+
+      [path, line, column].compact.join(":")
+    end
+  end
+
+  # Raised when the parser itself fails unexpectedly. Sätteri is pre-1.0, so a
+  # panic is converted into this instead of aborting the whole Ruby process.
+  class ParserError < Error; end
+
+  # Raised by Schema#validate! when frontmatter fails validation. Carries
+  # every Schema::Problem found (Zod-style: report everything in one pass)
+  # so a fix-and-rerun cycle can address all of them instead of one at a
+  # time, and names the offending file when a path is available so the
+  # message is actionable straight out of a build log.
+  class ValidationError < Error
+    attr_reader :problems, :path
+
+    def initialize(problems, path: nil)
+      @problems = problems
+      @path = path
+      lines = problems.map { |problem| path ? "#{path}: #{problem.message}" : problem.message }
+      super(lines.join("\n"))
+    end
+  end
+
+  # Raised by Loader#load when one or more files fail to load (validation
+  # failures, syntax errors, duplicate ids). Like ValidationError, this
+  # collects everything found across every file in one build rather than
+  # stopping at the first bad file, so a fix-and-rerun cycle can address all
+  # of them at once instead of playing whack-a-mole one file at a time.
+  class LoaderError < Error
+    attr_reader :messages
+
+    def initialize(messages)
+      @messages = messages
+      super(messages.join("\n"))
+    end
+  end
+
+  # Raised by Entry.find / Andromeda.get_entry when no entry has the given
+  # id. Lists near-miss ids (by edit distance) when any are close enough to
+  # plausibly be a typo -- e.g. `find("hello-wrold")` should hint at
+  # `hello-world` rather than just saying "not found".
+  class EntryNotFound < Error
+    attr_reader :collection, :id, :candidates
+
+    def initialize(collection:, id:, candidates: [])
+      @collection = collection
+      @id = id
+      @candidates = candidates
+
+      message = "no #{collection.inspect} entry with id #{id.to_s.inspect}"
+      hints = near_misses(id.to_s, candidates)
+      message += ". Did you mean #{hints.map(&:inspect).join(" or ")}?" unless hints.empty?
+      super(message)
+    end
+
+    private
+
+    # Only surfaces candidates within a small edit distance -- a long list
+    # of unrelated ids would be noise, not a hint.
+    def near_misses(id, candidates, max: 3, threshold: 4)
+      candidates
+        .map { |candidate| [candidate, levenshtein_distance(id, candidate)] }
+        .select { |_, distance| distance <= threshold }
+        .sort_by { |_, distance| distance }
+        .first(max)
+        .map(&:first)
+    end
+
+    # Classic Wagner-Fischer DP. No gem dependency for what is, at v0 scale
+    # (everything held in memory), a handful of short string comparisons.
+    def levenshtein_distance(a, b)
+      return b.length if a.empty?
+      return a.length if b.empty?
+
+      costs = (0..b.length).to_a
+      a.each_char.with_index(1) do |char_a, i|
+        last_diagonal = costs[0]
+        costs[0] = i
+        b.each_char.with_index(1) do |char_b, j|
+          old_cost = costs[j]
+          costs[j] = if char_a == char_b
+                       last_diagonal
+                     else
+                       [costs[j] + 1, costs[j - 1] + 1, last_diagonal + 1].min
+                     end
+          last_diagonal = old_cost
+        end
+      end
+      costs.last
+    end
+  end
+
+  # Raised by Andromeda::Pipeline#fetch/#collection_index in production mode
+  # when a request asks for an entry/collection that
+  # `andromeda:build` has never converted -- production never converts on
+  # demand, so this is the "you forgot to build" error rather than a
+  # transient failure, and the message says exactly what fixes it.
+  class BuildMissing < Error
+    attr_reader :collection, :id, :file_path
+
+    def initialize(collection:, id: nil, file_path: nil)
+      @collection = collection
+      @id = id
+      @file_path = file_path
+
+      target = id ? "#{collection}/#{id}" : collection.to_s
+      source = file_path ? " (source: #{file_path})" : ""
+      super(
+        "no converted output for #{target.inspect}#{source} -- run `bin/rails andromeda:build` to convert " \
+        "content into .andromeda/ (this also happens automatically as part of `assets:precompile`)"
+      )
+    end
+  end
+
+  # Raised by Andromeda::Pipeline#build_collection/.build_all (and
+  # #refresh_collection in development) when one or more entries fail to
+  # convert -- a schema problem, an unregistered MDX component, a syntax
+  # error, and so on. Like Andromeda::LoaderError, every problem found is
+  # collected first and raised together, so a build reports everything in
+  # one pass instead of a fix-and-rerun cycle one file at a time.
+  class BuildError < Error
+    attr_reader :messages
+
+    def initialize(messages)
+      @messages = messages
+      super(messages.join("\n"))
+    end
+  end
+
+  # Raised by Andromeda.get_collection / Andromeda.get_entry when no Entry
+  # subclass has registered the given collection name (see
+  # Andromeda::Registry) -- most often because its class has not been
+  # loaded yet in a development boot where app/ is not eager loaded.
+  class UnknownCollection < Error
+    def initialize(name)
+      super(
+        "no collection registered for #{name.inspect} -- does an Andromeda::Entry " \
+        "subclass call `collection #{name.inspect}, base: ...`? In development this " \
+        "class must be loaded first; see Andromeda::Registry.discover"
+      )
+    end
+  end
+end

data/lib/andromeda/fix.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Andromeda
+  # Rewrites frontmatter keys that are not snake_case, the one migration
+  # step content copied from an Astro project reliably needs.
+  #
+  # The rewrite is textual on purpose: round-tripping through a YAML/TOML
+  # emitter would reformat quoting, key order and comments, turning a
+  # two-key rename into an unreviewable diff.
+  module Fix
+    KEY_LINE = /\A(\s*)(["']?)([A-Za-z_][A-Za-z0-9_-]*)\2(\s*[:=]\s*)/
+
+    module_function
+
+    # @param entry_classes [Array<Class>] defaults to every registered collection.
+    # @param write [Boolean] false previews the changes without touching disk.
+    # @return [Array<String>] one line per renamed key, ready to print.
+    def run(entry_classes = Andromeda::Pipeline.default_entry_classes, write: true)
+      changes = []
+
+      content_files(entry_classes).each do |path|
+        source = File.read(path)
+        fixed, renames = fix_source(source)
+        next if renames.empty?
+
+        File.write(path, fixed) if write
+        renames.each { |from, to| changes << "#{path}: #{from} -> #{to}" }
+      end
+
+      changes
+    end
+
+    # @return [Array(String, Array<Array(String, String)>)] the rewritten
+    #   source and the renames applied to it.
+    def fix_source(source)
+      frontmatter, _format, = Andromeda::Frontmatter.split(source)
+      return [source, []] if frontmatter.nil?
+
+      renames = []
+      fixed_frontmatter = frontmatter.lines.map do |line|
+        match = KEY_LINE.match(line)
+        # Only top-level keys are renamed: an indented key belongs to a
+        # nested structure whose shape the schema does not describe.
+        next line unless match && match[1].empty?
+
+        key = match[3]
+        snake = snake_case(key)
+        next line if snake == key
+
+        renames << [key, snake]
+        line.sub(KEY_LINE) { "#{match[1]}#{match[2]}#{snake}#{match[2]}#{match[4]}" }
+      end.join
+
+      [source.sub(frontmatter, fixed_frontmatter), renames]
+    end
+
+    def snake_case(key)
+      key
+        .gsub("-", "_")
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    def content_files(entry_classes)
+      entry_classes.flat_map do |entry_class|
+        Dir.glob(File.join(entry_class.base_dir, entry_class.pattern)).sort
+      end
+    end
+  end
+end