markdown_composer 0.7.0

data/docs/compose/md_composer_compose_actions.md

@@ -0,0 +1,338 @@
+---
+title: Markdown Composer Compose Actions
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to compose actions, target rules, modify, and buffer-target actions.
+---
+
+# Markdown Composer Compose Actions
+
+### References
+
+| What | Where |
+|------|-------|
+| Compose anatomy | [./md_composer_compose_anatomy.md](./md_composer_compose_anatomy.md) |
+| Targets | [./md_composer_compose_targets.md](./md_composer_compose_targets.md) |
+| Modify example | [../examples/md_composer_example_modify.md](../examples/md_composer_example_modify.md) |
+
+---
+
+## 1. Purpose
+
+`action` tells Markdown Composer how a compose row changes the output buffer.
+
+```ruby
+{ "select" => "heading_2_section[first:1]", "action" => "set" }
+```
+
+If omitted, `action` defaults to `set`.
+
+## 2. Syntax Anatomy
+
+An action is one field in the compose row, but it only makes sense beside `select`, `include`, and sometimes `target`.
+
+```text
+compose_row = source + select + include + action + target
+
+action = action_token
+
+action_token = set
+             | append
+             | prepend
+             | insert_before
+             | insert_after
+             | insert_between
+             | replace
+             | copy
+             | move
+             | modify
+             | remove_buffer_target
+             | transform_buffer_target
+
+target_selector = unit_token [take] [where condition]
+```
+
+The target selector belongs to the `target` field, but action rules decide when it is required:
+
+```text
+replace target = target_selector | whole output | output
+
+insert_before target = target_selector
+insert_after target = target_selector
+insert_between target = between target_selector and target_selector
+
+remove_buffer_target target = target_selector
+transform_buffer_target target = target_selector
+
+modify target = start | end | before target_selector | after target_selector
+              | between target_selector and target_selector | in_place
+```
+
+Aliases are normalized before execution:
+
+| Alias | Normal action |
+|-------|---------------|
+| `take` | `set` |
+| `insert before` | `insert_before` |
+| `insert after` | `insert_after` |
+| `insert between` | `insert_between` |
+| `remove` | `remove_buffer_target` when used as a buffer-target action |
+
+## 3. Action Decision Table
+
+| Need | Use |
+|------|-----|
+| Start or replace the whole output buffer. | `set` |
+| Add selected source content to the end. | `append` |
+| Add selected source content to the start. | `prepend` |
+| Insert selected content before a buffer match. | `insert_before` |
+| Insert selected content after a buffer match. | `insert_after` |
+| Insert selected content between two buffer matches. | `insert_between` |
+| Replace buffer content with selected source content. | `replace` |
+| Duplicate selected content near a target. | `copy` |
+| Move selected buffer content near a target. | `move` |
+| Transform selected source content before placing it. | `modify` |
+| Remove existing buffer content by target selector. | `remove_buffer_target` |
+| Transform existing buffer content by target selector. | `transform_buffer_target` |
+
+## 4. Actions
+
+### 4.1. Set
+
+`set` replaces the whole buffer with selected and included source content. It is the default action.
+
+```ruby
+{
+  "select" => "heading_2_section[first:1]",
+  "include" => "all",
+  "action" => "set"
+}
+```
+
+Use `set` for the first row of most plans. A supplied custom `target` is ignored by execution because `set` always replaces the buffer.
+
+### 4.2. Append
+
+`append` adds selected content to the end of the buffer.
+
+```ruby
+{
+  "select" => "heading_2_section[last:1]",
+  "include" => "all",
+  "action" => "append"
+}
+```
+
+Leave `target` blank. A supplied custom `target` is ignored because append always writes to the end.
+
+### 4.3. Prepend
+
+`prepend` adds selected content to the start of the buffer.
+
+```ruby
+{
+  "select" => "paragraph where text:contains(\"Summary\")",
+  "include" => "all",
+  "action" => "prepend"
+}
+```
+
+Leave `target` blank. Use `insert_before` when you need a specific anchor rather than the absolute start.
+
+### 4.4. Insert Before
+
+`insert_before` places selected source content before a target selector in the current buffer.
+
+```ruby
+{
+  "select" => "paragraph where text:contains(\"Important\")",
+  "include" => "all",
+  "action" => "insert_before",
+  "target" => "heading_2 where text:contains(\"API\")"
+}
+```
+
+The target must be a selector, not `start` or `end`. The selector uses target anatomy:
+
+```text
+unit_token[take] where condition
+```
+
+### 4.5. Insert After
+
+`insert_after` places selected source content after a target selector in the current buffer.
+
+```ruby
+{
+  "select" => "code_block where language:equals(\"ruby\")",
+  "include" => "all",
+  "action" => "insert_after",
+  "target" => "heading_3 where text:contains(\"Example\")"
+}
+```
+
+Use it when the target anchor should remain before the inserted content.
+
+### 4.6. Insert Between
+
+`insert_between` places selected source content between two buffer anchors.
+
+```ruby
+{
+  "select" => "paragraph where text:contains(\"Release note\")",
+  "include" => "all",
+  "action" => "insert_between",
+  "target" => "between heading_2 where text:contains(\"Start\") and heading_2 where text:contains(\"End\")"
+}
+```
+
+The start anchor must resolve before the end anchor. Otherwise the target is invalid for insertion.
+
+### 4.7. Replace
+
+`replace` replaces matching buffer content with selected source content.
+
+```ruby
+{
+  "select" => "heading_2_section where title:equals(\"New API\")",
+  "include" => "all",
+  "action" => "replace",
+  "target" => "heading_2_section where title:equals(\"Old API\")"
+}
+```
+
+Use a selector target for precise replacement. Use `whole output` only when replacing the entire buffer is the intended result.
+
+### 4.8. Copy
+
+`copy` duplicates selected content near a buffer target. It does not remove the source selection.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "heading_2_section where title:equals(\"Install\")",
+  "include" => "all",
+  "action" => "copy",
+  "target" => "after heading_2 where text:contains(\"Quickstart\")"
+}
+```
+
+Use `source: "buffer"` when copying content that is already in the composition buffer.
+
+### 4.9. Move
+
+`move` removes selected buffer content from its original location and inserts it at the target.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "heading_2_section where title:equals(\"Appendix\")",
+  "include" => "all",
+  "action" => "move",
+  "target" => "end"
+}
+```
+
+`move` is most predictable when the selection comes from `source: "buffer"` because the action is relocating existing buffer content.
+
+### 4.10. Modify
+
+`modify` transforms selected source content in a temporary fragment, then places the transformed fragment at `target`.
+
+```ruby
+{
+  "select" => "heading_2_section where title:equals(\"Draft\")",
+  "include" => "all",
+  "action" => "modify",
+  "target" => "end",
+  "transforms" => [
+    {
+      "scope" => "paragraph",
+      "transform" => "replace_text",
+      "mode" => "literal",
+      "options" => { "from" => "Draft", "to" => "Final" }
+    }
+  ]
+}
+```
+
+Execution shape:
+
+1. Select source content.
+2. Apply `include`.
+3. Build a temporary fragment.
+4. Run nested transforms against that fragment.
+5. Place the transformed fragment at `target`.
+
+No target means `end`. `modify` does not edit existing buffer content unless `target` is `in_place`.
+
+### 4.11. Modify In Place
+
+`target: "in_place"` is a special `modify` target. It rewrites selected buffer content inline.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "paragraph where text:contains(\"Draft\")",
+  "include" => "all",
+  "action" => "modify",
+  "target" => "in_place",
+  "transforms" => [
+    { "transform" => "replace_text", "mode" => "literal", "options" => "from:Draft; to:Final" }
+  ]
+}
+```
+
+Rules:
+
+| Rule | Meaning |
+|------|---------|
+| `source` must be `buffer`. | Validation checks the original source field. |
+| `action` must be `modify`. | Other actions do not use `in_place`. |
+| Nested transforms must be valid. | The fragment is transformed before it is written back. |
+
+`source: "previous"` is not enough even if it resolves to the buffer; use `source: "buffer"` explicitly.
+
+### 4.12. Remove Buffer Target
+
+`remove_buffer_target` removes existing buffer content matched by `target`.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "all",
+  "action" => "remove_buffer_target",
+  "target" => "heading_2_section where title:equals(\"Deprecated\")"
+}
+```
+
+The meaningful field is `target`, not the selected source content. The target must be a selector target, not `start`, `end`, or `whole output`.
+
+### 4.13. Transform Buffer Target
+
+`transform_buffer_target` transforms existing buffer content matched by `target`.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "all",
+  "action" => "transform_buffer_target",
+  "target" => "heading_2_section where title:equals(\"Links\")",
+  "transforms" => [
+    { "transform" => "links", "mode" => "rewrite_url", "options" => { "from" => "http://", "to" => "https://" } }
+  ]
+}
+```
+
+If a nested transform omits `scope`, the action target becomes its scope. An explicit nested `scope` overrides the action target.
+
+## 5. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Treating `modify` as the same as `transform_buffer_target`. | Use `modify` for selected source fragments; use `transform_buffer_target` for existing buffer content. |
+| Using old `modify: { transforms: ... }` payloads. | Use row `"transforms" => [...]`. |
+| Using `start`, `end`, or `output` with buffer-target actions. | Use a selector target. |
+| Calling `take` an action. | Put take inside `select` or `include`. |
+| Supplying custom targets for `set`, `append`, or `prepend`. | Leave target blank; these actions use their built-in buffer locations. |

data/docs/compose/md_composer_compose_anatomy.md

@@ -0,0 +1,156 @@
+---
+title: Markdown Composer Compose Anatomy
+type: guide
+status: current
+updated: 2026-06-01
+description: Public anatomy guide for Markdown Composer compose rows.
+---
+
+# Markdown Composer Compose Anatomy
+
+### References
+
+| What | Where |
+|------|-------|
+| Sources | [./md_composer_compose_sources.md](./md_composer_compose_sources.md) |
+| Select | [./md_composer_compose_select.md](./md_composer_compose_select.md) |
+| Include | [./md_composer_compose_include.md](./md_composer_compose_include.md) |
+| Actions | [./md_composer_compose_actions.md](./md_composer_compose_actions.md) |
+| Targets | [./md_composer_compose_targets.md](./md_composer_compose_targets.md) |
+| Buffer | [./md_composer_compose_buffer.md](./md_composer_compose_buffer.md) |
+
+---
+
+## 1. Row Shape
+
+A compose row builds or edits the output buffer.
+
+```text
+Source -> Select -> Include -> Action -> Target
+```
+
+Read it as a sentence:
+
+```text
+From Source, select matching units, include the parts you want, then perform Action at Target.
+```
+
+Example:
+
+```ruby
+{
+  "source" => "current",
+  "select" => "heading_2_section where title:equals(\"API\")",
+  "include" => "all",
+  "action" => "set"
+}
+```
+
+This means: from the current source, find the H2 section titled `API`, keep the whole section, and set the buffer to that content.
+
+## 2. Field Responsibilities
+
+| Field | Responsibility | Common mistake |
+|-------|----------------|----------------|
+| `source` | Chooses where the row reads from. | Using `buffer` before anything has created buffer content. |
+| `select` | Chooses source units. | Selecting a heading node when you meant a whole section. |
+| `include` | Chooses what to keep from each selected unit. | Expecting `include` to select across the whole document. It runs inside each selected unit. |
+| `action` | Chooses how selected content changes the buffer. | Treating `take` as an action. Take belongs in `select` or `include`. |
+| `target` | Chooses where in the buffer the action applies. | Using `start` or `end` with buffer-target actions that require selector targets. |
+
+## 3. Minimal Row
+
+If you omit fields, the plan normalizes to defaults:
+
+| Field | Default |
+|-------|---------|
+| `source` | `current` |
+| `select` | `all` |
+| `include` | `all` |
+| `action` | `set` |
+| `target` | action-specific default |
+
+Minimal config:
+
+```ruby
+config = {
+  "compose" => [
+    { "select" => "heading_2_section[first:1]" }
+  ]
+}
+```
+
+Because `action` defaults to `set`, this sets the buffer to the first H2 section.
+
+## 4. Multi-Row Composition
+
+Rows run in order. Later rows can use earlier buffer content.
+
+```ruby
+config = {
+  "compose" => [
+    { "select" => "heading_2_section where title:equals(\"Intro\")", "action" => "set" },
+    { "select" => "heading_2_section where title:equals(\"API\")", "action" => "append" },
+    {
+      "source" => "buffer",
+      "select" => "all",
+      "action" => "remove_buffer_target",
+      "target" => "paragraph where text:contains(\"draft\")"
+    }
+  ]
+}
+```
+
+The first row creates the buffer, the second row appends to it, and the third row removes matching content from the buffer.
+
+## 5. String And Hash Forms
+
+Most author-facing fields accept compact strings or structured hashes.
+
+```ruby
+"select" => "heading_2_section[first:1] where title:contains(\"Intro\")"
+```
+
+Equivalent structured shape:
+
+```ruby
+"select" => {
+  "type" => "heading_2_section",
+  "take" => { "first" => 1 },
+  "where" => { "field" => "title", "predicate" => "contains", "value" => "Intro" }
+}
+```
+
+Use strings for hand-written docs, spreadsheets, and examples. Use hashes for GUI builders, stored presets, and generated plans.
+
+## 6. Action Families
+
+| Family | Actions | Reads selected source content? |
+|--------|---------|--------------------------------|
+| Buffer creation | `set` | yes |
+| Buffer insertion | `append`, `prepend`, `insert_before`, `insert_after`, `insert_between` | yes |
+| Buffer replacement | `replace` | yes |
+| Buffer relocation | `copy`, `move` | `copy` yes; `move` should use buffer selection |
+| Fragment transformation | `modify` | yes |
+| Existing-buffer mutation | `remove_buffer_target`, `transform_buffer_target` | no |
+
+`modify` is powerful because it lets one compose row select a source fragment, run nested transforms against that fragment, and place the result in the buffer.
+
+## 7. Validation And Diagnostics
+
+Run validation before saving a plan:
+
+```ruby
+validation = MarkdownComposer.validate(config: config, sources: sources)
+```
+
+Common compose diagnostics:
+
+| Diagnostic | Meaning |
+|------------|---------|
+| `source.missing` | The selected source cannot be resolved. |
+| `selection.empty` | The selector matched no content. |
+| `action.target_required` | The action needs a target. |
+| `target.selector_required` | A buffer-target action needs a selector target. |
+| `target.in_place_source_invalid` | `in_place` requires original `source: "buffer"`. |
+

data/docs/compose/md_composer_compose_buffer.md

@@ -0,0 +1,81 @@
+---
+title: Markdown Composer Compose Buffer
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to the Markdown Composer composition buffer and buffer-oriented actions.
+---
+
+# Markdown Composer Compose Buffer
+
+### References
+
+| What | Where |
+|------|-------|
+| Compose anatomy | [./md_composer_compose_anatomy.md](./md_composer_compose_anatomy.md) |
+| Actions | [./md_composer_compose_actions.md](./md_composer_compose_actions.md) |
+| Targets | [./md_composer_compose_targets.md](./md_composer_compose_targets.md) |
+
+---
+
+## 1. Purpose
+
+The buffer is the Markdown document being built. Compose rows write to it; target matching reads from it.
+
+```text
+row 1 -> buffer
+row 2 -> buffer
+row 3 -> buffer
+transforms -> final output
+```
+
+## 2. Buffer Lifecycle
+
+| Moment | What happens |
+|--------|--------------|
+| Before rows | Buffer starts empty, unless the caller passes an initial buffer. |
+| `set` | Replaces buffer with selected content. |
+| `append` / `prepend` | Adds content to buffer. |
+| Targeted actions | Match target selectors against current buffer. |
+| Top-level transforms | Run after all compose rows. |
+
+If a plan has no compose rows and there is one current source, the source content can be used as initial output.
+
+## 3. Reading From The Buffer
+
+Use `source: "buffer"` when selection should run against composed output.
+
+```ruby
+{
+  "source" => "buffer",
+  "select" => "heading_2_section where title:contains(\"Draft\")",
+  "include" => "all",
+  "action" => "modify",
+  "target" => "in_place",
+  "transforms" => [
+    { "transform" => "replace_text", "mode" => "literal", "options" => "from:Draft; to:Final" }
+  ]
+}
+```
+
+## 4. Buffer-Target Actions
+
+These actions operate on existing buffer content:
+
+| Action | Uses selected source content? | Main address |
+|--------|-------------------------------|--------------|
+| `remove_buffer_target` | no | `target` |
+| `transform_buffer_target` | no | `target` |
+| `modify` with `target: in_place` | yes, from buffer selection | `select` plus `target: in_place` |
+
+## 5. Stages For Debugging
+
+When supported by caller options, stages can show how the buffer changes after each row.
+
+```ruby
+result = MarkdownComposer.compose(sources: sources, config: config, options: { stages: true })
+pp result.stages
+```
+
+Use stages when a multi-row plan is hard to reason about.
+

data/docs/compose/md_composer_compose_examples.md

@@ -0,0 +1,31 @@
+---
+title: Markdown Composer Compose Examples
+type: examples
+status: current
+updated: 2026-06-01
+description: Compose-focused example index for Markdown Composer.
+---
+
+# Markdown Composer Compose Examples
+
+### References
+
+| What | Where |
+|------|-------|
+| Basic compose | [../examples/md_composer_example_basic_compose.md](../examples/md_composer_example_basic_compose.md) |
+| Multi-row compose | [../examples/md_composer_example_multi_row_compose.md](../examples/md_composer_example_multi_row_compose.md) |
+| Modify | [../examples/md_composer_example_modify.md](../examples/md_composer_example_modify.md) |
+| Buffer actions | [../examples/md_composer_example_buffer_target_actions.md](../examples/md_composer_example_buffer_target_actions.md) |
+
+---
+
+## 1. Example Map
+
+| Need | Example |
+|------|---------|
+| Select one section | [Basic compose](../examples/md_composer_example_basic_compose.md) |
+| Build output from several sections | [Multi-row compose](../examples/md_composer_example_multi_row_compose.md) |
+| Transform selected source content while composing | [Modify](../examples/md_composer_example_modify.md) |
+| Remove or transform existing buffer content | [Buffer target actions](../examples/md_composer_example_buffer_target_actions.md) |
+| Extract YAML/JSON values | [Structured data](../examples/md_composer_example_structured_data.md) |
+