andromeda_cms 0.1.0

data/ext/andromeda_cms/src/nodes.rs

@@ -0,0 +1,400 @@
+//! Walks a Sätteri `Arena<Mdast>` and renders it as mdast-spec-shaped JSON.
+//!
+//! This hand-written decode (rather than `#[derive(Serialize)]`) is
+//! necessary: Sätteri stores node-specific fields as a binary
+//! `#[repr(C)]` blob (`type_data`) rather than an idiomatic Rust enum, so
+//! each node type needs its own `XxxData::from_bytes` call
+//! (`satteri-ast`'s design targets its own napi/TS layer, not
+//! third-party Rust embedders).
+//!
+//! Every node here also carries a unist `position`
+//! (start/end line, column, offset). The gem needs
+//! line numbers to build `path:line:column: message` errors, so positions
+//! are not optional here.
+
+use satteri_arena::{decode_string_ref_data, Arena, Mdast, StringRef};
+use satteri_ast::mdast::codec::*;
+use satteri_ast::mdast::MdastNodeType;
+use serde_json::{json, Map, Value};
+
+fn get_str(arena: &Arena<Mdast>, sr: StringRef) -> String {
+    arena.get_str(sr).to_string()
+}
+
+fn opt_str(arena: &Arena<Mdast>, sr: StringRef) -> Value {
+    if sr.is_empty() {
+        Value::Null
+    } else {
+        Value::String(get_str(arena, sr))
+    }
+}
+
+/// unist `Position`: 1-based line/column (as Sätteri's `LineIndex` computes
+/// them — UTF-16-code-unit columns, matching what remark/unist report) and a
+/// byte offset (Sätteri does not track a separate UTF-16 offset per node, so
+/// `offset` is a byte index here; this is the one field that does not match
+/// mdast-util-from-markdown exactly, and only matters for tooling that
+/// slices `source[start.offset...end.offset]` on non-ASCII input).
+fn position(arena: &Arena<Mdast>, id: u32) -> Value {
+    let node = arena.get_node(id);
+    json!({
+        "start": {
+            "line": node.start_line,
+            "column": node.start_column,
+            "offset": node.start_offset,
+        },
+        "end": {
+            "line": node.end_line,
+            "column": node.end_column,
+            "offset": node.end_offset,
+        },
+    })
+}
+
+/// Whether mdast-util-from-markdown would emit a `children` array for this
+/// node type, even when empty (a unist `Parent`) as opposed to leaving it
+/// out entirely (a unist `Literal`/leaf). Kept as an explicit allow-list
+/// rather than "non-empty children" so an empty paragraph/root/etc still
+/// round-trips as `children: []` instead of silently losing the field.
+fn is_parent(nt: MdastNodeType) -> bool {
+    matches!(
+        nt,
+        MdastNodeType::Root
+            | MdastNodeType::Paragraph
+            | MdastNodeType::Heading
+            | MdastNodeType::Emphasis
+            | MdastNodeType::Strong
+            | MdastNodeType::Delete
+            | MdastNodeType::Blockquote
+            | MdastNodeType::List
+            | MdastNodeType::ListItem
+            | MdastNodeType::Link
+            | MdastNodeType::LinkReference
+            | MdastNodeType::Table
+            | MdastNodeType::TableRow
+            | MdastNodeType::TableCell
+            | MdastNodeType::FootnoteDefinition
+            | MdastNodeType::Superscript
+            | MdastNodeType::Subscript
+            | MdastNodeType::ContainerDirective
+            | MdastNodeType::LeafDirective
+            | MdastNodeType::TextDirective
+            | MdastNodeType::DescriptionList
+            | MdastNodeType::DescriptionTerm
+            | MdastNodeType::DescriptionDetails
+            | MdastNodeType::MdxJsxFlowElement
+            | MdastNodeType::MdxJsxTextElement
+    )
+}
+
+/// Best-effort decode of a node's `type_data` into JSON fields, keyed by
+/// mdast-spec field names. Node types not covered here (e.g. `thematicBreak`,
+/// `break`) have no extra fields in the spec either, so they fall through to
+/// `{}`.
+fn type_fields(arena: &Arena<Mdast>, id: u32, nt: MdastNodeType) -> Value {
+    let data = arena.get_type_data(id);
+    match nt {
+        MdastNodeType::Text
+        | MdastNodeType::InlineCode
+        | MdastNodeType::Html
+        | MdastNodeType::Yaml
+        | MdastNodeType::Toml
+        | MdastNodeType::MdxFlowExpression
+        | MdastNodeType::MdxTextExpression
+        | MdastNodeType::MdxjsEsm => {
+            if data.is_empty() {
+                json!({ "value": "" })
+            } else {
+                let sr = decode_string_ref_data(data);
+                json!({ "value": get_str(arena, sr) })
+            }
+        }
+        MdastNodeType::Math | MdastNodeType::InlineMath => {
+            if data.len() >= 16 {
+                let d = MathData::from_bytes(data);
+                json!({
+                    "meta": opt_str(arena, d.meta),
+                    "value": get_str(arena, d.value),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Heading => {
+            if !data.is_empty() {
+                json!({ "depth": data[0] })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Link => {
+            if !data.is_empty() {
+                let d = LinkData::from_bytes(data);
+                json!({
+                    "url": get_str(arena, d.url),
+                    "title": opt_str(arena, d.title),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Image => {
+            if !data.is_empty() {
+                let d = ImageData::from_bytes(data);
+                json!({
+                    "url": get_str(arena, d.url),
+                    "alt": opt_str(arena, d.alt),
+                    "title": opt_str(arena, d.title),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Code => {
+            if !data.is_empty() {
+                let d = CodeData::from_bytes(data);
+                json!({
+                    "lang": opt_str(arena, d.lang),
+                    "meta": opt_str(arena, d.meta),
+                    "value": get_str(arena, d.value),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::List => {
+            if !data.is_empty() {
+                let d = ListData::from_bytes(data);
+                json!({
+                    "ordered": d.ordered,
+                    "start": if d.ordered { Value::from(d.start) } else { Value::Null },
+                    "spread": d.spread,
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::ListItem => {
+            if !data.is_empty() {
+                let d = ListItemData::from_bytes(data);
+                json!({
+                    "checked": match d.checked { 0 => Value::Bool(false), 1 => Value::Bool(true), _ => Value::Null },
+                    "spread": d.spread,
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::DescriptionDetails => {
+            if !data.is_empty() {
+                let d = DescriptionDetailsData::from_bytes(data);
+                json!({ "spread": d.spread })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::LinkReference
+        | MdastNodeType::ImageReference
+        | MdastNodeType::FootnoteReference => {
+            if !data.is_empty() {
+                let d = ReferenceData::from_bytes(data);
+                let kind = match d.reference_kind {
+                    0 => "shortcut",
+                    1 => "collapsed",
+                    _ => "full",
+                };
+                let mut fields = Map::new();
+                fields.insert(
+                    "identifier".into(),
+                    Value::String(get_str(arena, d.identifier)),
+                );
+                fields.insert("label".into(), opt_str(arena, d.label));
+                // mdast spec: only link/imageReference carry referenceType,
+                // not footnoteReference.
+                if nt != MdastNodeType::FootnoteReference {
+                    fields.insert("referenceType".into(), Value::String(kind.into()));
+                }
+                // imageReference alone also carries `alt`, stored as a trailing
+                // StringRef appended after the shared ReferenceData header (see
+                // satteri_ast::mdast::codec::encode_image_reference_data).
+                if nt == MdastNodeType::ImageReference {
+                    let alt = decode_image_reference_alt(data);
+                    fields.insert("alt".into(), opt_str(arena, alt));
+                }
+                Value::Object(fields)
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::FootnoteDefinition => {
+            if !data.is_empty() {
+                let d = FootnoteDefinitionData::from_bytes(data);
+                json!({
+                    "identifier": get_str(arena, d.identifier),
+                    "label": opt_str(arena, d.label),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Definition => {
+            if !data.is_empty() {
+                let d = DefinitionData::from_bytes(data);
+                json!({
+                    "url": get_str(arena, d.url),
+                    "title": opt_str(arena, d.title),
+                    "identifier": get_str(arena, d.identifier),
+                    "label": opt_str(arena, d.label),
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::Table => {
+            // TableData header (align_count: u32) followed by align_count
+            // ColumnAlign bytes (see satteri_ast::mdast::codec::TableData).
+            if data.len() >= 4 {
+                let count = u32::from_le_bytes(data[0..4].try_into().unwrap()) as usize;
+                let mut aligns = vec![];
+                for i in 0..count {
+                    let b = *data.get(4 + i).unwrap_or(&0);
+                    aligns.push(match b {
+                        1 => Value::String("left".into()),
+                        2 => Value::String("right".into()),
+                        3 => Value::String("center".into()),
+                        _ => Value::Null,
+                    });
+                }
+                json!({ "align": aligns })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::ContainerDirective
+        | MdastNodeType::LeafDirective
+        | MdastNodeType::TextDirective => {
+            if data.len() >= 12 {
+                let name = decode_directive_name(data);
+                let attr_count = decode_directive_attr_count(data);
+                let mut attrs = Map::new();
+                for i in 0..attr_count {
+                    let (key, value) = decode_directive_attr(data, i);
+                    attrs.insert(get_str(arena, key), Value::String(get_str(arena, value)));
+                }
+                json!({
+                    "name": get_str(arena, name),
+                    "attributes": attrs,
+                })
+            } else {
+                json!({})
+            }
+        }
+        MdastNodeType::MdxJsxFlowElement | MdastNodeType::MdxJsxTextElement => {
+            if data.len() >= 16 {
+                let name_sr = decode_mdx_jsx_element_name(data);
+                let attr_count = decode_mdx_jsx_attr_count(data);
+                let name = if name_sr.is_empty() {
+                    Value::Null // fragment (<>...</>)
+                } else {
+                    Value::String(get_str(arena, name_sr))
+                };
+                let mut attrs = vec![];
+                for i in 0..attr_count {
+                    let (kind, attr_name, attr_value) = decode_mdx_jsx_attr(data, i);
+                    if kind == 3 {
+                        // spread ({...expr}): no name, value is the raw
+                        // expression text.
+                        attrs.push(json!({
+                            "type": "mdxJsxExpressionAttribute",
+                            "value": get_str(arena, attr_value),
+                        }));
+                        continue;
+                    }
+                    let value = match kind {
+                        0 => Value::Null,                               // boolean prop
+                        1 => Value::String(get_str(arena, attr_value)), // literal
+                        _ => {
+                            json!({ "type": "mdxJsxAttributeValueExpression", "value": get_str(arena, attr_value) })
+                        } // expression prop
+                    };
+                    attrs.push(json!({
+                        "type": "mdxJsxAttribute",
+                        "name": get_str(arena, attr_name),
+                        "value": value,
+                    }));
+                }
+                json!({ "name": name, "attributes": attrs })
+            } else {
+                json!({ "name": Value::Null, "attributes": Value::Array(vec![]) })
+            }
+        }
+        MdastNodeType::Custom => {
+            if data.len() >= 16 {
+                let name = StringRef::from_bytes(&data[0..8]);
+                let value = StringRef::from_bytes(&data[8..16]);
+                json!({
+                    "customType": get_str(arena, name),
+                    "value": opt_str(arena, value),
+                })
+            } else {
+                json!({})
+            }
+        }
+        _ => json!({}),
+    }
+}
+
+/// The first node (in document order) that sits more than `limit` levels
+/// below `root`, if any.
+///
+/// Deliberately iterative: it runs before the recursive `node_to_json`, so
+/// it must not be the thing that overflows the stack on the input it exists
+/// to reject.
+pub fn first_node_deeper_than(arena: &Arena<Mdast>, root: u32, limit: usize) -> Option<u32> {
+    let mut pending = vec![(root, 0usize)];
+    while let Some((id, depth)) = pending.pop() {
+        if depth > limit {
+            return Some(id);
+        }
+        let parent = MdastNodeType::from_u8(arena.get_node(id).node_type).is_some_and(is_parent);
+        if parent {
+            pending.extend(
+                arena
+                    .get_children(id)
+                    .iter()
+                    .rev()
+                    .map(|&child| (child, depth + 1)),
+            );
+        }
+    }
+    None
+}
+
+/// Recursively renders one arena node (and its subtree) as mdast JSON.
+pub fn node_to_json(arena: &Arena<Mdast>, id: u32) -> Value {
+    let node = arena.get_node(id);
+    let nt = MdastNodeType::from_u8(node.node_type);
+    let type_name = nt.map(|t| t.name()).unwrap_or("unknown").to_string();
+
+    let mut obj = Map::new();
+    obj.insert("type".into(), Value::String(type_name));
+    if let Some(nt) = nt {
+        if let Value::Object(fields) = type_fields(arena, id, nt) {
+            for (k, v) in fields {
+                obj.insert(k, v);
+            }
+        }
+    }
+
+    if let Some(nt) = nt {
+        if is_parent(nt) {
+            let children = arena.get_children(id);
+            let arr: Vec<Value> = children.iter().map(|&c| node_to_json(arena, c)).collect();
+            obj.insert("children".into(), Value::Array(arr));
+        }
+    }
+
+    obj.insert("position".into(), position(arena, id));
+
+    Value::Object(obj)
+}

data/lib/andromeda/assets.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Andromeda
+  # Publishes images that live next to content so the asset pipeline can serve
+  # them.
+  #
+  # Adding `app/content` to Propshaft's load path would be shorter, but
+  # Propshaft serves *every* file in a load path — the Markdown sources
+  # themselves would become public URLs. Copying only the referenced images
+  # into `app/assets/builds/andromeda/` keeps the content directory private and
+  # mirrors how tailwindcss-rails treats `app/assets/builds`.
+  module Assets
+    # Relative to `app/assets/builds`, and therefore also the prefix of the
+    # logical asset path the view helpers resolve.
+    DIRECTORY = "andromeda"
+
+    module_function
+
+    # Copies `source` under the builds directory and returns its logical path
+    # (what `asset_path` takes), or nil when the file is not a publishable
+    # asset under the content root.
+    #
+    # @param source [String] absolute path to a file inside the content root.
+    # @param content_root [String] the collection's base directory.
+    # @return [String, nil] e.g. "andromeda/blog/post/cover.png".
+    def publish(source, content_root:)
+      logical = logical_path(source, content_root: content_root)
+      return nil if logical.nil?
+
+      return logical if asset_pipeline_path(File.expand_path(source))
+
+      destination = File.join(builds_root, logical)
+      FileUtils.mkdir_p(File.dirname(destination))
+      # Copying only when the content changed keeps `andromeda:build` cheap on
+      # image-heavy sites, where the copy would otherwise dominate the run.
+      FileUtils.cp(source, destination) unless identical?(source, destination)
+      logical
+    end
+
+    # Conversion cannot know an image's final URL: Propshaft only learns the
+    # digest when `assets:precompile` runs, which is *after* `andromeda:build`
+    # (it depends on it), and in development the load path is indexed at boot.
+    # So the stored HTML carries this marker and the view resolves it, which
+    # costs one gsub per render and keeps digests correct in both environments.
+    MARKER = "andromeda-asset:"
+
+    def marker_for(logical_path)
+      "#{MARKER}#{logical_path}"
+    end
+
+    # @param html [String] stored HTML, possibly containing markers.
+    # @return [String] the same HTML with every marker replaced by a real URL.
+    def resolve(html)
+      return html unless html.include?(MARKER)
+
+      html.gsub(/#{Regexp.escape(MARKER)}([^"'\s)]+)/) { url_for(Regexp.last_match(1)) }
+    end
+
+    # @return [String] a URL for a logical path, digest-stamped when the asset
+    #   pipeline is available and a plain /assets path otherwise.
+    def url_for(logical_path)
+      if defined?(::ActionController::Base)
+        ::ActionController::Base.helpers.asset_path(logical_path)
+      else
+        File.join("/assets", logical_path)
+      end
+    rescue StandardError
+      # An image that has not been indexed yet (a fresh copy in development,
+      # or a precompile that has not run) must not take the whole page down.
+      File.join("/assets", logical_path)
+    end
+
+    def logical_path(source, content_root:)
+      source = File.expand_path(source)
+      root = File.expand_path(content_root)
+      project = project_root
+
+      # Nothing outside the project (or the content root, when a collection
+      # lives elsewhere) may be published: a `../` chain in a content file
+      # must not expose an arbitrary file on the machine.
+      inside = [project, root].any? { |boundary| source.start_with?("#{boundary}#{File::SEPARATOR}") }
+      return nil unless inside
+
+      if source.start_with?("#{root}#{File::SEPARATOR}")
+        File.join(DIRECTORY, File.basename(root), source.delete_prefix("#{root}#{File::SEPARATOR}"))
+      elsif (asset_relative = asset_pipeline_path(source))
+        asset_relative
+      else
+        # Somewhere else in the project (Astro's own example keeps hero
+        # images in `src/assets`): mirrored under the build directory so it
+        # still gets a digest, with the project-relative path kept to avoid
+        # collisions between same-named files.
+        File.join(DIRECTORY, "project", source.delete_prefix("#{project}#{File::SEPARATOR}"))
+      end
+    end
+
+    # A file the asset pipeline already serves needs no copy -- returning its
+    # logical path lets `asset_path` digest the original in place.
+    def asset_pipeline_path(source)
+      assets_root = File.join(project_root, "app/assets")
+      return nil unless source.start_with?("#{assets_root}#{File::SEPARATOR}")
+
+      relative = source.delete_prefix("#{assets_root}#{File::SEPARATOR}")
+      # Propshaft's load path is each directory under app/assets, so the
+      # first segment (images/, stylesheets/, builds/, ...) is not part of
+      # the logical path -- except for files sitting directly in app/assets.
+      relative.include?(File::SEPARATOR) ? relative.split(File::SEPARATOR, 2).last : relative
+    end
+
+    def project_root
+      Andromeda.config.project_root
+    end
+
+    def builds_root
+      File.join(project_root, "app/assets/builds")
+    end
+
+    # Compares bytes, not timestamps: a checkout or an extracted archive can
+    # give a changed image an old mtime, and a same-sized edit would then
+    # never be copied. The size check keeps the common case cheap.
+    def identical?(source, destination)
+      File.exist?(destination) && File.size(source) == File.size(destination) &&
+        FileUtils.compare_file(source, destination)
+    end
+  end
+end

data/lib/andromeda/check.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Andromeda
+  # The read-only counterpart of `andromeda:build`, for CI.
+  #
+  # It deliberately runs the *same* conversion the build runs, into a
+  # throwaway store, rather than re-implementing a subset of the checks: a
+  # check that passes while the build fails would be worse than no check at
+  # all. Everything it finds is reported together, because fixing content
+  # one error per CI run is miserable.
+  module Check
+    module_function
+
+    # @param entry_classes [Array<Class>] defaults to every registered collection.
+    # @return [Array<String>] human-readable problems; empty when content is healthy.
+    def run(entry_classes = Andromeda::Pipeline.default_entry_classes)
+      problems = []
+
+      entry_classes.each do |entry_class|
+        entries = load_entries(entry_class, problems)
+        next if entries.nil?
+
+        entries.each do |entry|
+          problems.concat(frontmatter_style_problems(entry))
+          problems.concat(conversion_problems(entry))
+        end
+      end
+
+      problems
+    end
+
+    def load_entries(entry_class, problems)
+      entry_class.reload!
+      entry_class.all.to_a
+    rescue Andromeda::LoaderError => e
+      problems.concat(e.messages.map { |message| "[#{entry_class.collection_name}] #{message}" })
+      nil
+    rescue Andromeda::Error => e
+      problems << "[#{entry_class.collection_name}] #{e.message}"
+      nil
+    end
+
+    # Non-snake_case keys are legal YAML but will not reach a declared
+    # attribute, so they are reported here with the command that rewrites
+    # them instead of failing later as a missing required field.
+    def frontmatter_style_problems(entry)
+      offenders = Andromeda::Frontmatter.non_snake_case_keys(entry.data)
+      return [] if offenders.empty?
+
+      offenders.map do |key|
+        "#{entry.file_path}: frontmatter key #{key} is not snake_case; run `bin/rails andromeda:fix`"
+      end
+    end
+
+    def conversion_problems(entry)
+      Andromeda::Pipeline.new(store: NullStore.new, mode: :development).convert(entry)
+      []
+    rescue Andromeda::Error => e
+      ["#{entry.file_path}: #{e.message}"]
+    end
+
+    # Swallows the writes so a check can never leave `.andromeda/` in a
+    # half-built state that a later production boot would happily serve.
+    class NullStore
+      def write_entry(*) = nil
+      def read_entry(*) = nil
+      def read_index(*) = nil
+      def replace_collection!(*) = nil
+    end
+  end
+end

data/lib/andromeda/components/errors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Andromeda
+  class Components
+    # Raised when a component tag resolves to a partial name (by explicit
+    # registration, import path, or naming convention) but no such partial
+    # exists on disk. Names the tag, the content file, the line, and the
+    # exact path to create so the error is actionable straight out
+    # of a build log or a development error page, without having to go
+    # spelunking through the resolution rules to figure out what Andromeda
+    # was even looking for.
+    class MissingPartialError < Andromeda::Error
+      attr_reader :tag_name, :path, :line, :expected_path
+
+      def initialize(tag_name, path:, line:, expected_path:)
+        @tag_name = tag_name
+        @path = path
+        @line = line
+        @expected_path = expected_path
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: <#{tag_name}> has no matching partial. Create #{expected_path} " \
+          "(e.g. `rails g andromeda:component #{tag_name}`), register it explicitly with " \
+          "`Andromeda::Components.register(#{tag_name.to_s.inspect}, \"partial/path\")`, or " \
+          "import it from a path that points at an existing partial."
+        )
+      end
+    end
+
+    # Raised for a member-expression tag name (`<Tabs.Item>`) that
+    # was not explicitly registered. Convention-based resolution can't turn
+    # a dotted name into a partial path, and guessing would be more
+    # surprising than just saying so -- named-slot components (the
+    # `Tabs`/`Fragment slot=` pattern) cover the common case this syntax is
+    # usually reaching for.
+    class InvalidComponentNameError < Andromeda::Error
+      attr_reader :tag_name, :path, :line
+
+      def initialize(tag_name, path:, line:)
+        @tag_name = tag_name
+        @path = path
+        @line = line
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: <#{tag_name}> looks like a member expression (e.g. `Tabs.Item`), " \
+          "which Andromeda does not resolve by naming convention in v0 -- register it " \
+          "explicitly with `Andromeda::Components.register(#{tag_name.to_s.inspect}, " \
+          "\"partial/path\")`"
+        )
+      end
+    end
+
+    # Raised for a `{...}` expression that is neither a literal,
+    # a `frontmatter.x` reference, nor a comment -- the
+    # v0 static-expression subset. Everything else (`.map()`,
+    # ternaries, template interpolation, arrow functions, `await`, ...) is
+    # explicitly out of scope, and silently dropping it would hide content
+    # bugs, so this raises naming the file/line rather than degrading
+    # quietly.
+    class UnsupportedExpressionError < Andromeda::Error
+      attr_reader :source, :path, :line, :column
+
+      def initialize(source, path:, line:, column:)
+        @source = source
+        @path = path
+        @line = line
+        @column = column
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: unsupported MDX expression `{#{source}}` -- only literals, " \
+          "`frontmatter.x` references, and comments are supported"
+        )
+      end
+    end
+
+    # Raised when there is no Rails renderer to hand a partial to -- either
+    # `ApplicationController` is not defined (Rails is not loaded / not
+    # booted yet) and no `view:` was passed explicitly to
+    # `Andromeda::Components.new`. Components render through
+    # `ApplicationController.renderer`; there is no non-Rails fallback in
+    # v0 (a plain ActionView::Base renderer setup is enough of a project on
+    # its own -- view paths, compiled template caching, helpers -- that it
+    # is deferred rather than half-done here).
+    class NoRendererAvailableError < Andromeda::Error
+      def initialize(path)
+        super(
+          "no Rails renderer available to render MDX components in " \
+          "#{path || "(unknown file)"} -- define ApplicationController, or pass `view:` " \
+          "explicitly to Andromeda::Components.new"
+        )
+      end
+    end
+  end
+end