markdown_composer 0.7.0

data/examples/standard_composer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+
+sources = MarkdownComposer.source_list do
+  current File.read(File.join(root, "fixtures/current.md"))
+end
+
+# Select one H2 section, keep focused content, then promote the heading levels.
+plan = MarkdownComposer.plan do
+  output :markdown
+
+  from :current
+  select 'h2_section where title:equals("Feature Matrix")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  include "link[first:1]"
+  include "table[first:1]"
+  include "heading_3_section[position:1,2] { heading_title; paragraph[first:1]; code_block; table }"
+  append
+
+  transform "heading_2", "replace_text", "literal", {
+    "from" => "Feature Matrix",
+    "to" => "Feature Matrix Summary"
+  }
+
+  transform "heading", "heading_levels", "promote", {
+    "by" => 1
+  }
+
+  transform "paragraph[first:1]", "insert_after", "insert", {
+    "content" => "\n## Summary\n\nThis generated summary highlights the selected feature table and the two focused child sections.",
+    "as" => "paragraph"
+  }
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+
+ExampleSupport.write_output(root, "standard_composer", result)

data/examples/standard_sources_buffer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+
+sources = MarkdownComposer.source_list do
+  current File.read(File.join(root, "fixtures/current.md"))
+  explicit :guide, File.read(File.join(root, "fixtures/guide.md"))
+end
+
+# Compose from current, reuse the explicit source with previous, then trim via buffer.
+plan = MarkdownComposer.plan do
+  output :markdown
+
+  from :current
+  select "heading_1_section[first:1]"
+  include "heading_title"
+  include "paragraph[first:1]"
+  set
+
+  from :current
+  select 'h2_section where title:equals("Operations")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  include "heading_3_section[first:1] { heading_title; paragraph[first:1]; code_block }"
+  append
+
+  from({ type: "explicit", key: "guide" })
+  select 'h2_section where title:equals("Install")'
+  include "all"
+  append
+
+  from :previous
+  select 'h2_section where title:equals("Validate")'
+  include "all"
+  append
+
+  from :buffer
+  select 'h2_section where title:equals("Install")'
+  remove_buffer_target
+
+  transform "heading_2", "replace_text", "literal", {
+    "from" => "Operations",
+    "to" => "Standard Operations"
+  }
+
+  transform "heading_3", "replace_text", "literal", {
+    "from" => "Deployment",
+    "to" => "Release Steps"
+  }
+
+  transform "output", "heading_numbers", "rebuild", {
+    "levels" => [ "h2", "h3" ],
+    "start" => 1
+  }
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+
+ExampleSupport.write_output(root, "standard_sources_buffer", result)

data/examples/yaml_plan.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+
+sources = MarkdownComposer.source_list do
+  current File.read(File.join(root, "fixtures/current.md"))
+  explicit :guide, File.read(File.join(root, "fixtures/guide.md"))
+end
+
+# Load the compose and transform plan from YAML instead of the Ruby DSL.
+plan = MarkdownComposer.parse_yaml(File.read(File.join(root, "plans/basic.yml")))
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+
+ExampleSupport.write_output(root, "yaml_plan", result)

data/lib/markdown_composer/capabilities.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module MarkdownComposer
+  module Capabilities
+    module_function
+
+    VERSION = 1
+
+    def build(options = {})
+      registries = Registries.default
+      json_compatible({
+        version: VERSION,
+        headless: true,
+        fields: field_metadata,
+        formats: format_metadata,
+        sources: entries(registries.sources, :source, options),
+        actions: entries(registries.actions, :action, options),
+        targets: entries(registries.targets, :target, options),
+        unit_tokens: entries(registries.unit_tokens, nil, options),
+        take: entries(registries.take, :take, options),
+        where: {
+          fields: entries(registries.condition_fields, nil, options),
+          predicates: entries(registries.predicates, :predicate, options),
+          groups: entries(registries.where_groups, nil, options),
+          condition_map: registries.conditions
+        },
+        transforms: transform_entries(registries.transforms, options),
+        outputs: output_metadata,
+        diagnostic_code_families: diagnostic_code_families,
+        policy_options: policy_options
+      })
+    end
+
+    def entries(registry, support_key, options)
+      registry.to_a.map do |entry|
+        support = entry[:support] || entry["support"] || {}
+        base = entry.dup
+        base[:support_status] = support_key ? support_status(support[support_key] || support[support_key.to_s], options) : support_status_from_support_hash(support, options)
+        base[:enabled] = enabled_status?(base[:support_status])
+        base
+      end
+    end
+
+    def transform_entries(registry, options)
+      registry.entries.map do |entry|
+        modes = Array(entry.support[:modes])
+        mode_metadata = modes.map { |mode| transform_mode_metadata(entry, mode, options) }
+        support_status = support_status(entry.support[:transform], options)
+        {
+          token: entry.token,
+          aliases: entry.aliases,
+          label: entry.label,
+          tooltip: entry.tooltip,
+          meaning: entry.meaning,
+          row_sentence: entry.row_sentence,
+          support: entry.support,
+          support_status: support_status,
+          enabled: enabled_status?(support_status),
+          modes: mode_metadata,
+          source_formats: entry.source_formats,
+          condition_fields: entry.condition_fields
+        }
+      end
+    end
+
+    def transform_mode_metadata(entry, mode, options)
+      required = TransformOptions.required(entry.token, mode)
+      optional = TransformOptions.optional(entry.token, mode, adapter_option_keys: options[:adapter_option_keys])
+      status = transform_mode_status(entry.token, mode, options)
+      {
+        token: mode,
+        label: mode.to_s.split("_").map(&:capitalize).join(" "),
+        support_status: status,
+        enabled: enabled_status?(status),
+        required_options: required,
+        optional_options: optional,
+        policy_gated: %w[policy_gated disabled_policy].include?(status),
+        required_output: required_output(entry.token, mode),
+        required_policy_options: required_policy_options(entry.token, mode)
+      }
+    end
+
+    def transform_mode_status(transform, mode, options)
+      transform = transform.to_s
+      mode = mode.to_s
+      return "policy_gated" if transform == "adapter"
+      return "policy_gated" if transform == "sanitise"
+      return "policy_gated" if transform == "order" && mode == "target_order"
+
+      "normal"
+    end
+
+    def required_output(transform, mode)
+      return "html" if transform.to_s == "links" && %w[nofollow target_blank].include?(mode.to_s)
+
+      nil
+    end
+
+    def required_policy_options(transform, mode)
+      transform = transform.to_s
+      mode = mode.to_s
+      return [ "adapter_transforms" ] if transform == "adapter" || transform == "sanitise"
+
+      []
+    end
+
+    def support_status(value, options)
+      case value.to_sym
+      when :normal then "normal"
+      when :advanced then "advanced"
+      when :output_only then "output_only"
+      when :include_only then "include_only"
+      when :optional then options.fetch(:optional_tokens, false) ? "optional" : "disabled_optional"
+      when :adapter_policy then options.fetch(:adapter_policy_tokens, false) ? "policy_gated" : "disabled_policy"
+      else "disabled"
+      end
+    end
+
+    def support_status_from_support_hash(support, options)
+      statuses = support.values.map { |value| support_status(value, options) }
+      return "disabled" if statuses.empty?
+
+      %w[normal include_only output_only advanced optional policy_gated].find { |status| statuses.include?(status) } || statuses.first
+    end
+
+    def enabled_status?(status)
+      !%w[disabled disabled_optional disabled_policy policy_gated].include?(status.to_s)
+    end
+
+    def format_metadata
+      {
+        input: [
+          { from: "markdown", support_status: "normal", fidelity: "source" },
+          { from: "html", support_status: "best_effort", fidelity: "lossy" }
+        ],
+        conversions: [
+          { from: "markdown", to: "markdown", support_status: "normal", fidelity: "source" },
+          { from: "markdown", to: "html", support_status: "normal", fidelity: "rendered" },
+          { from: "html", to: "markdown", support_status: "best_effort", fidelity: "lossy" },
+          { from: "html", to: "html", support_status: "best_effort", fidelity: "lossy_intermediate_markdown" }
+        ]
+      }
+    end
+
+    def field_metadata
+      {
+        source: {
+          label: "Source",
+          tooltip: "First row normally uses current or explicit sources; previous falls back to current when no prior row exists. Later rows may use inherited, previous source, or previous output after a row has produced output.",
+          first_row: %w[current explicit previous],
+          later_rows: %w[current explicit inherited previous buffer]
+        },
+        document: {
+          label: "Document",
+          tooltip: "Select a host document when Source is Explicit or Inherited. Current Source uses the preview source supplied by the host."
+        },
+        select: {
+          label: "Select",
+          tooltip: "Selector token from the registry. Supports take and where syntax such as heading_2_section[first:1]."
+        },
+        include: {
+          label: "Include",
+          tooltip: "Include token from the registry. Use all for the full selected content or a unit token such as heading_title."
+        },
+        action: {
+          label: "Action",
+          tooltip: "Composition action from the registry. Some actions require a target."
+        },
+        target: {
+          label: "Target",
+          tooltip: "Target selector or position used by insert, replace, copy, move, remove_buffer_target, and transform_buffer_target actions. For modify with source buffer, in_place replaces selected buffer content inline."
+        },
+        transform: {
+          label: "Transform",
+          tooltip: "Registered transform. GUIs should filter transforms and modes by enabled capability metadata."
+        },
+        mode: {
+          label: "Mode",
+          tooltip: "Transform mode from the capability contract. Some modes require options or HTML output."
+        },
+        scope: {
+          label: "Scope",
+          tooltip: "Transform scope selector. Usually output or a registry selector such as heading_2_section."
+        },
+        options: {
+          label: "Options JSON",
+          tooltip: "JSON object passed to the selected transform mode. Required and optional keys come from capabilities."
+        }
+      }
+    end
+
+    def output_metadata
+      [
+        { token: "markdown", aliases: [ "md" ], label: "Markdown", support_status: "normal" },
+        { token: "html", aliases: [], label: "HTML", support_status: "normal" }
+      ]
+    end
+
+    def diagnostic_code_families
+      %w[action json output source selector take target token transform where yaml]
+    end
+
+    def policy_options
+      [
+        { token: "adapter_policy_tokens", default: false, unlocks: "host-policy token families such as raw_html" },
+        { token: "adapter_transforms", default: false, unlocks: "host-policy transform families" }
+      ]
+    end
+
+    def json_compatible(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, child), hash| hash[key.to_s] = json_compatible(child) }
+      when Array
+        value.map { |child| json_compatible(child) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+  end
+end