markdown_composer 0.7.0

data/examples/advanced_composer.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+
+# A comprehensive Ruby DSL example:
+# - runtime sources: current, explicit, inherited
+# - row sources: inline, previous, buffer
+# - actions: set, append, prepend, insert_before, insert_after, insert_between,
+#   replace, copy, move, modify, remove_buffer_target, transform_buffer_target
+# - transforms: scoped text replacement, insertion, dedupe, link rewrite, 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 }"
+  set
+
+  from({
+    type: "inline",
+    markdown: "### Advanced Preface\n\nThis section is prepended first, then moved into a better reading position."
+  })
+  select "h3_section"
+  include "all"
+  prepend
+
+  from({ type: "inherited", key: "site_intro" })
+  select 'h2_section where title:equals("Welcome")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  append
+
+  transform_buffer_target(
+    'h2 where title:equals("Welcome")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => {
+          "by" => 1
+        }
+      }
+    ]
+  )
+
+  from({ type: "explicit", key: "guide" })
+  select 'h2_section where title:equals("Validate")'
+  include "all"
+  append
+
+  from :previous
+  select 'h2_section where title:equals("Publish")'
+  include "all"
+  append
+
+  transform_buffer_target(
+    'h2 where title:equals("Validate")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => {
+          "by" => 1
+        }
+      },
+      {
+        "scope" => "heading_3",
+        "transform" => "replace_text",
+        "mode" => "word",
+        "options" => {
+          "from" => "Validate",
+          "to" => "Validation Snapshot"
+        }
+      }
+    ]
+  )
+
+  transform_buffer_target(
+    'h2 where title:equals("Publish")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => {
+          "by" => 1
+        }
+      },
+      {
+        "scope" => "heading_3",
+        "transform" => "replace_text",
+        "mode" => "word",
+        "options" => {
+          "from" => "Publish",
+          "to" => "Release Checklist"
+        }
+      }
+    ]
+  )
+
+  from({
+    type: "inline",
+    markdown: "### Release Note\n\nThis inserted note shows small inline Markdown inside a larger plan."
+  })
+  select "h3_section"
+  include "all"
+  insert_before 'h3_section where title:equals("Automation")'
+
+  from :current
+  select 'h3_section where title:equals("Reporting")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  replace 'h3_section where title:equals("Automation")'
+
+  from({
+    type: "inline",
+    markdown: "### Support Note\n\nThis note is inserted between two existing composed sections."
+  })
+  select "h3_section"
+  include "all"
+  insert_between 'Between h3_section where title:equals("Release Note") and h3_section where title:equals("Reporting")'
+
+  from :current
+  select 'h3_section where title:equals("Monitoring")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  insert_after 'h3_section where title:equals("Reporting")'
+
+  from :buffer
+  select 'h3_section where title:equals("Release Note")'
+  include "all"
+  copy "end"
+
+  from :buffer
+  select 'h3_section where title:equals("Dashboard")'
+  include "all"
+  modify "in_place", transforms: [
+    {
+      "scope" => "heading_3, paragraph",
+      "transform" => "replace_text",
+      "mode" => "literal",
+      "options" => {
+        "from" => "Dashboard",
+        "to" => "Dashboard Snapshot"
+      }
+    },
+    {
+      "scope" => "paragraph[first:1]",
+      "transform" => "insert_after",
+      "mode" => "insert",
+      "options" => {
+        "content" => "This paragraph was inserted by the modify action before final output transforms run.",
+        "as" => "paragraph"
+      }
+    }
+  ]
+
+  from :buffer
+  select 'h3_section where title:equals("Advanced Preface")'
+  include "all"
+  move 'after h2_section where title:equals("Feature Matrix")'
+
+  from({
+    type: "inline",
+    markdown: "### Cleanup Marker\n\nThis temporary marker exists only to demonstrate remove_buffer_target."
+  })
+  select "h3_section"
+  include "all"
+  append
+
+  from :buffer
+  select 'h3_section where title:equals("Cleanup Marker")'
+  remove_buffer_target
+
+  transform "output", "dedupe", "normalised_text"
+
+  transform "heading_2", "replace_text", "literal", {
+    "from" => "Feature Matrix",
+    "to" => "Advanced Composer Walkthrough"
+  }
+
+  transform "link[first:1]", "links", "rewrite_url", {
+    "from" => "/features/dashboard",
+    "to" => "https://example.test/features/dashboard"
+  }
+
+  transform "heading", "heading_levels", "promote", {
+    "by" => 1
+  }
+end
+
+result = MarkdownComposer.compose(
+  sources: MarkdownComposer.source_list do
+    current File.read(File.join(root, "fixtures/current.md"))
+    explicit :guide, File.read(File.join(root, "fixtures/guide.md"))
+    inherited :site_intro, File.read(File.join(root, "fixtures/site_intro.md"))
+  end,
+  plan: plan
+)
+
+ExampleSupport.write_output(root, "advanced_composer", result)

data/examples/basic_compose.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+current_markdown = File.read(File.join(root, "fixtures/current.md"))
+
+# Select the first H2 section from the current source and emit it unchanged.
+plan = MarkdownComposer.plan do
+  from :current
+  select "h2_section[first:1]"
+  include "all"
+  set
+end
+
+result = MarkdownComposer.compose(
+  sources: [
+    { key: "current", type: "current", markdown: current_markdown }
+  ],
+  plan: plan
+)
+
+ExampleSupport.write_output(root, "basic_compose", result)

data/examples/complex_composer.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "markdown_composer"
+require_relative "example_support"
+
+root = File.expand_path(__dir__)
+
+# The complex example is intentionally broad but still readable.
+# Sources live in the compose call at the bottom, so the plan stays focused.
+plan = MarkdownComposer.plan do
+  output :markdown
+
+  # Start with a focused current-source feature section.
+  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 }"
+  set
+
+  # Prepend an inline section, then move it later to demonstrate both actions.
+  from({
+    type: "inline",
+    markdown: "### Complex Preface\n\nThis section is prepended first, then moved into the final reading order."
+  })
+  select "h3_section"
+  include "all"
+  prepend
+
+  # Append inherited site copy and demote it while it is still in the buffer.
+  from({ type: "inherited", key: "site_intro" })
+  select 'h2_section where title:equals("Welcome")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  append
+
+  transform_buffer_target(
+    'h2 where title:equals("Welcome")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => { "by" => 1 }
+      }
+    ]
+  )
+
+  # Append explicit guide content, then use previous to keep working in guide.
+  from({ type: "explicit", key: "guide" })
+  select 'h2_section where title:equals("Validate")'
+  include "all"
+  append
+
+  from :previous
+  select 'h2_section where title:equals("Publish")'
+  include "all"
+  append
+
+  transform_buffer_target(
+    'h2 where title:equals("Validate")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => { "by" => 1 }
+      },
+      {
+        "scope" => "heading_3",
+        "transform" => "replace_text",
+        "mode" => "word",
+        "options" => { "from" => "Validate", "to" => "Validation Snapshot" }
+      }
+    ]
+  )
+
+  transform_buffer_target(
+    'h2 where title:equals("Publish")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => { "by" => 1 }
+      },
+      {
+        "scope" => "heading_3",
+        "transform" => "replace_text",
+        "mode" => "word",
+        "options" => { "from" => "Publish", "to" => "Release Checklist" }
+      }
+    ]
+  )
+
+  # Add an explicit FAQ section and keep only the useful summary pieces.
+  from({ type: "explicit", key: "faq" })
+  select 'h2_section where title:equals("What source types exist?")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  append
+
+  transform_buffer_target(
+    'h2 where title:equals("What source types exist?")',
+    transforms: [
+      {
+        "transform" => "heading_levels",
+        "mode" => "demote",
+        "options" => { "by" => 1 }
+      },
+      {
+        "scope" => "heading_3",
+        "transform" => "replace_text",
+        "mode" => "literal",
+        "options" => {
+          "from" => "What source types exist?",
+          "to" => "Source Type Notes"
+        }
+      }
+    ]
+  )
+
+  # Use inline source content with insert_before and insert_between.
+  from({
+    type: "inline",
+    markdown: "### Release Note\n\nThis inserted note shows small inline Markdown inside a larger plan."
+  })
+  select "h3_section"
+  include "all"
+  insert_before 'h3_section where title:equals("Automation")'
+
+  from({
+    type: "inline",
+    markdown: "### Support Note\n\nThis note is inserted between two existing composed sections."
+  })
+  select "h3_section"
+  include "all"
+  insert_between 'Between h3_section where title:equals("Release Note") and h3_section where title:equals("Automation")'
+
+  # Replace Automation with Reporting, then insert Monitoring after Reporting.
+  from :current
+  select 'h3_section where title:equals("Reporting")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  replace 'h3_section where title:equals("Automation")'
+
+  from :current
+  select 'h3_section where title:equals("Monitoring")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  insert_after 'h3_section where title:equals("Reporting")'
+
+  # Copy a section, then let final dedupe remove the duplicate content.
+  from :buffer
+  select 'h3_section where title:equals("Release Note")'
+  include "all"
+  copy "end"
+
+  # Modify an existing buffer section in place with two nested transforms.
+  from :buffer
+  select 'h3_section where title:equals("Dashboard")'
+  include "all"
+  modify "in_place", transforms: [
+    {
+      "scope" => "heading_3, paragraph",
+      "transform" => "replace_text",
+      "mode" => "literal",
+      "options" => {
+        "from" => "Dashboard",
+        "to" => "Dashboard Snapshot"
+      }
+    },
+    {
+      "scope" => "paragraph[first:1]",
+      "transform" => "insert_after",
+      "mode" => "insert",
+      "options" => {
+        "content" => "This paragraph was inserted by the modify action before final output transforms run.",
+        "as" => "paragraph"
+      }
+    }
+  ]
+
+  # Move the preface into the document body.
+  from :buffer
+  select 'h3_section where title:equals("Complex Preface")'
+  include "all"
+  move 'after h2_section where title:equals("Feature Matrix")'
+
+  # Add and remove temporary content to demonstrate remove_buffer_target.
+  from({
+    type: "inline",
+    markdown: "### Cleanup Marker\n\nThis temporary marker exists only to demonstrate remove_buffer_target."
+  })
+  select "h3_section"
+  include "all"
+  append
+
+  from :buffer
+  select 'h3_section where title:equals("Cleanup Marker")'
+  remove_buffer_target
+
+  # Final output transforms shape the composed Markdown.
+  transform "output", "dedupe", "normalised_text"
+
+  transform "heading_2", "replace_text", "literal", {
+    "from" => "Feature Matrix",
+    "to" => "Complex Composer Walkthrough"
+  }
+
+  transform "link[first:1]", "links", "rewrite_url", {
+    "from" => "/features/dashboard",
+    "to" => "https://example.test/features/dashboard"
+  }
+
+  transform "heading", "heading_levels", "promote", {
+    "by" => 1
+  }
+
+  transform "paragraph[first:1]", "insert_after", "insert", {
+    "content" => "\n## Summary\n\nThis summary was inserted by a final transform after composition actions completed.",
+    "as" => "paragraph"
+  }
+end
+
+result = MarkdownComposer.compose(
+  sources: MarkdownComposer.source_list do
+    current File.read(File.join(root, "fixtures/current.md"))
+    explicit :guide, File.read(File.join(root, "fixtures/guide.md"))
+    explicit :faq, File.read(File.join(root, "fixtures/faq.md"))
+    inherited :site_intro, File.read(File.join(root, "fixtures/site_intro.md"))
+  end,
+  plan: plan
+)
+
+ExampleSupport.write_output(root, "complex_composer", result)

data/examples/example_support.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ExampleSupport
+  module_function
+
+  # Keep example scripts small: fail loudly on Composer errors and write
+  # the generated Markdown beside the runnable examples.
+  def write_output(root, name, result)
+    abort result.errors.map(&:message).join("\n") unless result.success?
+
+    output_dir = File.join(root, "output")
+    Dir.mkdir(output_dir) unless Dir.exist?(output_dir)
+    path = File.join(output_dir, "#{name}.md")
+    File.write(path, result.markdown)
+    puts "Wrote #{path}"
+    puts result.markdown
+  end
+end

data/examples/fixtures/current.md

@@ -0,0 +1,179 @@
+# Product Knowledge Base
+
+Welcome to the product knowledge base. This file is the main `current` source for runnable examples.
+
+It intentionally contains several Markdown structures so you can experiment with selectors such as `h2_section`, `h3_section`, `paragraph[first:2]`, `table`, `code_block`, `mermaid`, and `math_block`.
+
+## Overview
+
+This overview section is the normal starting point for Markdown Composer examples.
+
+It includes [a product link](/features/dashboard), inline code `composer.preview`, and a second paragraph so include rules can choose content.
+
+### What Composer Should See
+
+Composer should index nested sections under Overview and keep selected content in source order.
+
+- The first bullet links to [getting started](/docs/getting-started).
+- The second bullet mentions `source_list`.
+- The third bullet is plain text for list-item selection.
+
+#### Selector Notes
+
+Use `h2_section[first:1]` to select the whole Overview section, including this H4.
+
+Use `paragraph[first:1]` inside an include rule to keep only the first paragraph.
+
+### What Composer Should Ignore
+
+This H3 gives you a second nested section to filter by title or position.
+
+> Blockquotes are useful for testing paragraph and block-level extraction.
+
+## Feature Matrix
+
+The table below is intended for table selection and table-row experiments.
+
+| Feature | Status | Owner | Link |
+| --- | --- | --- | --- |
+| Dashboard | ready | Product | [Open](/features/dashboard) |
+| Automation | beta | Platform | [Open](/features/automation) |
+| Reporting | draft | Data | [Open](/features/reporting) |
+
+### Dashboard
+
+Dashboard cards should keep this heading and paragraph when selected.
+
+| Card | Visible |
+| --- | --- |
+| Summary | yes |
+| Activity | yes |
+
+```ruby
+class DashboardCard
+  def visible?
+    status == "ready"
+  end
+end
+```
+
+#### Dashboard Deep Dive
+
+This H4 is nested under Dashboard and can be used to test deeper section boundaries.
+
+### Automation
+
+Automation has two paragraphs so examples can select first or last content.
+
+The second paragraph mentions API triggers, webhooks, retries, and scheduled jobs.
+
+| Trigger | Retry |
+| --- | --- |
+| webhook | yes |
+| schedule | yes |
+
+```bash
+bundle exec ruby automation_rule.rb
+```
+
+```json
+{
+  "feature": "automation",
+  "status": "beta",
+  "retries": 3
+}
+```
+
+### Reporting
+
+Reporting is marked draft so examples can filter it out by title or selected position.
+
+## Operations
+
+Operations content gives the examples runbook-style Markdown.
+
+### Deployment
+
+Deployment notes keep release steps short, repeatable, and easy to audit.
+
+1. Build the package.
+2. Run the test suite.
+3. Publish the generated gem.
+
+```bash
+bundle exec rake test
+gem build markdown_composer.gemspec
+```
+
+#### Rollback
+
+Rollback should happen only after the published package or integration has been verified.
+
+### Monitoring
+
+Monitor compose success rate, validation errors, and unexpected empty selections.
+
+## Diagrams And Math
+
+This section includes Mermaid and math examples.
+
+### Composition Flow
+
+The composition flow diagram shows the order used by the examples.
+
+```mermaid
+flowchart LR
+  Source --> Select
+  Select --> Include
+  Include --> Action
+  Action --> Buffer
+  Buffer --> Transform
+```
+
+### Score Formula
+
+Inline math can appear in prose as `$score = selected / total$`.
+
+Display math can appear as its own block:
+
+```math
+precision = true_positive / (true_positive + false_positive)
+```
+
+#### Formula Notes
+
+Math blocks and inline math are useful for testing token preservation.
+
+## Draft Notes
+
+This section is deliberately named Draft so examples can remove or filter it.
+
+### Cleanup Target
+
+Use this nested section to test `where title:contains("Cleanup")` or `h3_section[last:1]`.
+
+<!-- composer: removable draft comment -->
+
+## Appendix
+
+The appendix gives the main fixture a fifth H2 section.
+
+### Source Types
+
+Source type rows describe where content comes from during composition.
+
+| Source | Meaning |
+| --- | --- |
+| current | Main runtime source |
+| explicit | Keyed runtime source |
+| inherited | Host-resolved runtime source |
+| inline | Plan-row source content |
+
+### Copy-Paste Checklist
+
+Use this checklist when adapting the examples to a local script.
+
+- Read files with `File.read`.
+- Build sources with `MarkdownComposer.source_list`.
+- Build plans with `MarkdownComposer.plan` or `MarkdownComposer.parse_yaml`.
+- Run `MarkdownComposer.compose`.