markdown_composer 0.7.0

data/docs/transform/md_composer_transform_anatomy.md

@@ -0,0 +1,112 @@
+---
+title: Markdown Composer Transform Anatomy
+type: guide
+status: current
+updated: 2026-06-01
+description: Public anatomy guide for Markdown Composer transform rows.
+---
+
+# Markdown Composer Transform Anatomy
+
+### References
+
+| What | Where |
+|------|-------|
+| Scope | [./md_composer_transform_scope.md](./md_composer_transform_scope.md) |
+| Transforms | [./md_composer_transform_transforms.md](./md_composer_transform_transforms.md) |
+| Modes | [./md_composer_transform_modes.md](./md_composer_transform_modes.md) |
+| Options | [./md_composer_transform_options.md](./md_composer_transform_options.md) |
+| Transform examples | [./md_composer_transform_examples.md](./md_composer_transform_examples.md) |
+
+---
+
+## 1. Row Shape
+
+A transform row reshapes composed output.
+
+```text
+Scope -> Transform -> Mode -> Options
+```
+
+Full row anatomy:
+
+```text
+transform_row = {
+  scope: scope_selector | output,
+  transform: transform_family,
+  mode: family_mode,
+  options: option_hash | option_string
+}
+```
+
+Read it as a sentence:
+
+```text
+Inside this Scope, run this Transform in this Mode with these Options.
+```
+
+Example:
+
+```ruby
+{
+  "scope" => "output",
+  "transform" => "replace_text",
+  "mode" => "literal",
+  "options" => { "from" => "Draft", "to" => "Final" }
+}
+```
+
+## 2. Top-Level Transforms
+
+Top-level transforms run after all compose rows have finished building the buffer.
+
+```ruby
+config = {
+  "compose" => [
+    { "select" => "heading_2_section", "action" => "set" }
+  ],
+  "transform" => [
+    { "scope" => "output", "transform" => "heading_numbers", "mode" => "rebuild", "options" => { "levels" => [2] } }
+  ]
+}
+```
+
+If `scope` is omitted, it defaults to `output`.
+
+## 3. Row-Level Transforms
+
+Row-level transforms are used by actions that explicitly support nested transforms:
+
+| Action | What nested transforms affect |
+|--------|-------------------------------|
+| `modify` | A temporary fragment made from selected source content. |
+| `transform_buffer_target` | Existing buffer content matched by the action target, unless an explicit nested scope is supplied. |
+
+Row-level transforms are not a separate global pipeline. They belong to the compose row that declares them.
+
+## 4. Field Responsibilities
+
+| Field | Responsibility | Common mistake |
+|-------|----------------|----------------|
+| `scope` | Chooses which buffer units the transform changes. | Forgetting that top-level scope matches composed output, not original source. |
+| `transform` | Chooses the transform family. | Picking a transform without checking its modes. |
+| `mode` | Chooses behavior inside the transform family. | Assuming modes share the same required options. |
+| `options` | Provides transform-specific settings. | Treating options as JSON only; hashes and semicolon strings both work. |
+
+## 5. Validation
+
+Validation checks transform tokens, modes, required options, unknown option keys, option value types, and policy-gated transforms.
+
+```ruby
+validation = MarkdownComposer.validate(config: config, sources: sources)
+```
+
+Missing options produce `transform.option_missing`. Unknown options produce `transform.option_unknown`.
+
+## 6. Important Caveats
+
+| Caveat | Meaning |
+|--------|---------|
+| Optional options are validation metadata. | Some accepted optional keys are ahead of standalone runner behavior. |
+| HTML link attribute modes are special. | `links/nofollow` and `links/target_blank` apply during final HTML rendering for top-level transforms. |
+| Policy-gated modes are not ordinary features. | `adapter`, `sanitise`, and `order/target_order` need host policy or are deferred. |

data/docs/transform/md_composer_transform_examples.md

@@ -0,0 +1,30 @@
+---
+title: Markdown Composer Transform Examples
+type: examples
+status: current
+updated: 2026-06-01
+description: Transform-focused example index for Markdown Composer.
+---
+
+# Markdown Composer Transform Examples
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform anatomy | [./md_composer_transform_anatomy.md](./md_composer_transform_anatomy.md) |
+| Transform examples | [../examples/md_composer_example_transforms.md](../examples/md_composer_example_transforms.md) |
+| HTML output | [../examples/md_composer_example_html_output.md](../examples/md_composer_example_html_output.md) |
+
+---
+
+## 1. Example Map
+
+| Need | Example |
+|------|---------|
+| Replace text after composing | [Transform examples](../examples/md_composer_example_transforms.md) |
+| Use transform options | [Transform options](./md_composer_transform_options.md) |
+| Add HTML link attributes | [HTML output](../examples/md_composer_example_html_output.md) |
+| Transform during `modify` | [Modify](../examples/md_composer_example_modify.md) |
+| Transform an existing buffer target | [Buffer target actions](../examples/md_composer_example_buffer_target_actions.md) |
+

data/docs/transform/md_composer_transform_modes.md

@@ -0,0 +1,83 @@
+---
+title: Markdown Composer Transform Modes
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to transform modes and mode-specific behavior.
+---
+
+# Markdown Composer Transform Modes
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform families | [./md_composer_transform_transforms.md](./md_composer_transform_transforms.md) |
+| Options | [./md_composer_transform_options.md](./md_composer_transform_options.md) |
+| Capabilities | [../reference/md_composer_reference_capabilities.md](../reference/md_composer_reference_capabilities.md) |
+
+---
+
+## 1. Purpose
+
+`mode` selects behavior inside a transform family.
+
+```ruby
+{ "transform" => "heading_numbers", "mode" => "rebuild", "options" => { "levels" => [2] } }
+```
+
+Modes are transform-specific. Do not assume options from one mode work in another mode.
+
+## 2. Syntax Anatomy
+
+`mode` is not global. It is resolved inside the selected transform family.
+
+```text
+mode_key = transform_family "/" mode
+
+heading_numbers/rebuild
+replace_text/literal
+links/rewrite_url
+```
+
+The mode key controls:
+
+| Control | Example |
+|---------|---------|
+| Required options | `replace_text/literal` requires `from` and `to`. |
+| Optional options | `heading_numbers/rebuild` accepts `start`, `format`, and related keys. |
+| Output constraints | `links/nofollow` and `links/target_blank` are meaningful with HTML output. |
+| Policy gates | `order/target_order` is not a normal ready-to-use mode. |
+
+## 3. Mode Matrix
+
+| Transform | Modes |
+|-----------|-------|
+| `heading_numbers` | `keep`, `strip`, `add`, `rebuild` |
+| `replace_text` | `literal`, `word`, `regex` |
+| `links` | `keep`, `unwrap`, `remove`, `rewrite_url`, `nofollow`, `target_blank` |
+| `heading_levels` | `promote`, `demote`, `normalise` |
+| `remove_empty` | `remove` |
+| `insert_before`, `insert_after`, `prepend_content`, `append_content` | `insert` |
+| `replace_content` | `replace` |
+| `remove_content` | `remove` |
+| `dedupe` | `source_node_id`, `normalised_text` |
+| `order` | `action_order`, `source_order`, `target_order` |
+| `sanitise` | `block_safe`, `text_only`, `links_unwrapped`, `strict` |
+
+## 4. GUI Filtering Rule
+
+If you build a UI, filter by mode-level `enabled`, not only transform-level `enabled`.
+
+Example: `order` can be visible while `order/target_order` is gated. The mode metadata is the source of truth for whether a mode should be offered.
+
+## 5. HTML Link Attribute Modes
+
+`links/nofollow` and `links/target_blank` are special:
+
+| Rule | Meaning |
+|------|---------|
+| Require HTML output metadata | They are useful with `output: "html"`. |
+| Top-level post-processing | Final HTML link attributes are applied after Markdown rendering. |
+| Global external-link behavior | The renderer walks rendered links; it skips empty links and `#anchor` links. |
+| Row-level caveat | Row-level link attribute transforms do not update final HTML attributes. |

data/docs/transform/md_composer_transform_options.md

@@ -0,0 +1,142 @@
+---
+title: Markdown Composer Transform Options
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to transform options, hash syntax, semicolon syntax, required keys, and validation errors.
+---
+
+# Markdown Composer Transform Options
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform anatomy | [./md_composer_transform_anatomy.md](./md_composer_transform_anatomy.md) |
+| Modes | [./md_composer_transform_modes.md](./md_composer_transform_modes.md) |
+| Diagnostics | [../reference/md_composer_reference_diagnostics.md](../reference/md_composer_reference_diagnostics.md) |
+
+---
+
+## 1. Purpose
+
+`options` provides settings for a transform mode.
+
+```ruby
+{ "transform" => "replace_text", "mode" => "literal", "options" => { "from" => "Draft", "to" => "Final" } }
+```
+
+The field label in capabilities says `Options JSON`, but public authors can use either structured hashes or semicolon option strings.
+
+## 2. Syntax Anatomy
+
+`options` can be a structured hash/object or a compact semicolon string. Both forms normalize into the same option map before validation.
+
+```text
+options = option_hash | option_string
+
+option_hash = { key => value, key => value }
+
+option_string = key:value; key:value; key:value
+
+value = string | number | boolean | nil | unit_token | unit_list | target_selector
+```
+
+Option names and required keys depend on the selected transform/mode pair:
+
+```text
+transform + mode -> allowed option keys
+```
+
+Some option values have their own mini-grammar:
+
+| Option kind | Example | Notes |
+|-------------|---------|-------|
+| Text value | `from:"Draft"` | Quote values that contain punctuation or semicolons. |
+| Boolean | `case_sensitive:false` | Normalizes to `false`. |
+| Unit token | `unit:p` | Aliases normalize, for example `p` to `paragraph`. |
+| Unit list | `levels:h2,h3` | Comma-separated aliases normalize where supported. |
+| Target selector | `target:"heading_2_section[first:1]"` | Used by target-order style metadata and gated/deferred modes. |
+
+## 3. Hash Syntax
+
+Use hashes for Ruby code, JSON configs, generated plans, and GUI builders.
+
+```ruby
+"options" => {
+  "from" => "Draft",
+  "to" => "Final",
+  "case_sensitive" => false
+}
+```
+
+## 4. Semicolon String Syntax
+
+Use semicolon strings for compact authoring.
+
+```ruby
+"options" => "from:\"Draft\"; to:\"Final\"; case_sensitive:false"
+```
+
+The parser splits only at top-level semicolons, so quoted semicolons and nested expressions can survive.
+
+Values support:
+
+| Value form | Example |
+|------------|---------|
+| String | `from:"Draft"` |
+| Boolean | `case_sensitive:false` |
+| Nil | `target:nil` |
+| Integer | `limit:2` |
+| Unit aliases | `unit:p`, `as:paragraph`, `levels:h2,h3` |
+
+Option values normalize through unit token aliases where appropriate.
+
+## 5. Required Options
+
+| Transform / mode | Required |
+|------------------|----------|
+| `replace_text/literal` | `from`, `to` |
+| `replace_text/word` | `from`, `to` |
+| `replace_text/regex` | `from`, `to` |
+| `links/rewrite_url` | `from`, `to` |
+| `heading_numbers/add` | `levels` |
+| `heading_numbers/rebuild` | `levels` |
+| `heading_levels/promote` | `by` |
+| `heading_levels/demote` | `by` |
+| `heading_levels/normalise` | `to` |
+| `remove_empty/remove` | `unit` |
+| content insertion/replacement | `content`, `as` |
+| `order/target_order` | `target` |
+
+## 6. Optional Options
+
+Examples:
+
+| Transform / mode | Optional |
+|------------------|----------|
+| `heading_numbers/rebuild` | `start`, `format`, `exclude`, `restart_at` |
+| `replace_text/literal` | `case_sensitive`, `limit`, `whole_node` |
+| `links/rewrite_url` | `match`, `case_sensitive` |
+| `heading_levels/promote` | `min_level`, `max_level` |
+| `remove_empty/remove` | `trim`, `ignore_nbsp`, `ignore_comments` |
+| `insert_before/insert` | `dedupe`, `parse_as` |
+
+Some optional keys are validation metadata ahead of standalone runner behavior. Validate and test advanced options before promising them in a host UI.
+
+## 7. Validation Errors
+
+| Diagnostic | Meaning |
+|------------|---------|
+| `transform.option_missing` | A required option is absent. |
+| `transform.option_unknown` | The option key is not accepted for that transform/mode. |
+| `transform.options_syntax` | The options value is not a readable string or object. |
+| `transform.policy_required` | The transform requires host policy. |
+
+## 8. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Treating options as JSON only. | Use either hashes or semicolon strings. |
+| Copying options between modes. | Check the selected transform/mode pair. |
+| Passing `levels:2,3` and expecting raw integers only. | Levels may normalize aliases like `h2,h3` to canonical tokens. |

data/docs/transform/md_composer_transform_scope.md

@@ -0,0 +1,97 @@
+---
+title: Markdown Composer Transform Scope
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to transform scope syntax and behavior.
+---
+
+# Markdown Composer Transform Scope
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform anatomy | [./md_composer_transform_anatomy.md](./md_composer_transform_anatomy.md) |
+| Compose targets | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+| Select syntax | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Unit tokens | [../reference/md_composer_unit_tokens.md](../reference/md_composer_unit_tokens.md) |
+| Take modifiers | [../reference/md_composer_take.md](../reference/md_composer_take.md) |
+| Where conditions | [../reference/md_composer_where.md](../reference/md_composer_where.md) |
+
+---
+
+## 1. Purpose
+
+`scope` chooses which units in the composed buffer a transform should affect.
+
+```ruby
+{ "scope" => "heading_2_section[first:1]", "transform" => "replace_text", "mode" => "literal", "options" => "from:Draft; to:Final" }
+```
+
+If omitted, scope defaults to `output`.
+
+## 2. Syntax Anatomy
+
+Scope reuses selector syntax:
+
+```text
+scope = output | scope_selector
+
+scope_selector = unit_token [take] [where condition]
+```
+
+For every scope-capable token and alias, see [Unit Tokens](../reference/md_composer_unit_tokens.md).
+For shared scope-selector take syntax, see [Take Modifiers](../reference/md_composer_take.md).
+For shared scope-selector `where` syntax, see [Where Conditions](../reference/md_composer_where.md).
+
+Scope selector parts:
+
+| Part | Example | Meaning |
+|------|---------|---------|
+| `output` | `output` | The whole composed buffer or row fragment. |
+| `unit_token` | `heading_2_section`, `paragraph`, `link` | A unit matched inside the current transform input. |
+| `[take]` | `[first:1]`, `[position:2]` | Optional positional narrowing. |
+| `where condition` | `where text:contains("Draft")` | Optional filtering. |
+
+Examples:
+
+| Goal | Scope |
+|------|-------|
+| Whole composed output | `output` |
+| First H2 section in buffer | `heading_2_section[first:1]` |
+| Paragraphs with text | `paragraph where text:contains("Draft")` |
+| Code blocks | `code_block` |
+| Data blocks | `data_block where format:equals("yaml")` |
+
+## 3. Top-Level Scope
+
+Top-level transform scope matches the composed buffer after all compose rows have run. It does not search the original sources.
+
+```ruby
+{
+  "transform" => [
+    { "scope" => "output", "transform" => "replace_text", "mode" => "literal", "options" => "from:Draft; to:Final" }
+  ]
+}
+```
+
+## 4. Row-Level Scope
+
+For `modify`, omitted nested scope means the temporary fragment output.
+
+For `transform_buffer_target`, omitted nested scope means the action `target`. An explicit nested scope overrides the action target.
+
+## 5. Data Record And Data Value Scope
+
+Capabilities mark `data_record` and `data_value` as output-only scopes. In the standalone Markdown buffer, they are transient derived nodes produced by `data_path(...)` and then serialized back to Markdown. Do not rely on `scope: "data_record"` or `scope: "data_value"` after ordinary composition unless a host adapter preserves structured nodes.
+
+Use `data_block` scope for source-like structured blocks, or target the serialized Markdown text after extraction.
+
+## 6. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Expecting scope to search source documents. | Scope searches the composed buffer or row fragment. |
+| Omitting scope without understanding defaults. | Top-level transforms default to `output`; row-level defaults depend on action. |
+| Using `data_value` as a reliable standalone scope. | Treat it as transient structured-output metadata unless preserved by a host. |

data/docs/transform/md_composer_transform_transforms.md

@@ -0,0 +1,99 @@
+---
+title: Markdown Composer Transform Families
+type: guide
+status: current
+updated: 2026-06-01
+description: Public guide to Markdown Composer transform families.
+---
+
+# Markdown Composer Transform Families
+
+### References
+
+| What | Where |
+|------|-------|
+| Transform anatomy | [./md_composer_transform_anatomy.md](./md_composer_transform_anatomy.md) |
+| Modes | [./md_composer_transform_modes.md](./md_composer_transform_modes.md) |
+| Options | [./md_composer_transform_options.md](./md_composer_transform_options.md) |
+
+---
+
+## 1. Purpose
+
+`transform` chooses the family of operation to run. `mode` chooses the behavior inside that family.
+
+```ruby
+{ "transform" => "replace_text", "mode" => "literal", "options" => { "from" => "Draft", "to" => "Final" } }
+```
+
+## 2. Syntax Anatomy
+
+The `transform` field is only the family token. It is paired with `mode` and `options` to form an executable transform row.
+
+```text
+transform_row = scope + transform_family + mode + options
+
+transform_family = heading_numbers
+                 | replace_text
+                 | links
+                 | heading_levels
+                 | remove_empty
+                 | insert_before
+                 | insert_after
+                 | prepend_content
+                 | append_content
+                 | replace_content
+                 | remove_content
+                 | dedupe
+                 | order
+                 | sanitise
+                 | adapter
+
+mode = one mode supported by that family
+
+options = required and optional keys for that family/mode pair
+```
+
+Example anatomy:
+
+| Field | Value | Meaning |
+|-------|-------|---------|
+| `scope` | `paragraph where text:contains("Draft")` | Match paragraphs in the composed buffer. |
+| `transform` | `replace_text` | Use the text replacement family. |
+| `mode` | `literal` | Use literal text replacement. |
+| `options` | `from:"Draft"; to:"Final"` | Provide required replacement values. |
+
+## 3. Transform Families
+
+| Transform | Use for |
+|-----------|---------|
+| `heading_numbers` | Keep, strip, add, or rebuild heading numbering. |
+| `replace_text` | Replace literal text, whole words, or regex matches. |
+| `links` | Keep, unwrap, remove, rewrite URLs, or add HTML link attributes. |
+| `heading_levels` | Promote, demote, or normalize heading levels. |
+| `remove_empty` | Remove empty units. |
+| `insert_before` / `insert_after` | Insert content near scoped units. |
+| `prepend_content` / `append_content` | Add content inside or near scoped units. |
+| `replace_content` | Replace scoped content. |
+| `remove_content` | Remove scoped content. |
+| `dedupe` | Remove duplicates by source node id or normalized text. |
+| `order` | Preserve action/source order; target order is gated/deferred. |
+| `sanitise` | Host-policy sanitizing profiles. |
+| `adapter` | Host-provided transform behavior. |
+
+## 4. Common Choices
+
+| Need | Transform / mode |
+|------|------------------|
+| Rename a term | `replace_text/literal` |
+| Renumber headings | `heading_numbers/rebuild` |
+| Promote headings | `heading_levels/promote` |
+| Insert a warning before sections | `insert_before/insert` |
+| Remove empty paragraphs | `remove_empty/remove` |
+| Rewrite links | `links/rewrite_url` |
+
+## 5. Policy-Gated Families
+
+`sanitise` and `adapter` are policy-gated. A host must explicitly enable and implement policy behavior before exposing them as ordinary user controls.
+
+`order/target_order` is also gated/deferred in capabilities. Public docs should not present it as a normal ready-to-use transform.

data/examples/README.md

@@ -0,0 +1,20 @@
+# Markdown Composer Examples
+
+These examples are runnable Ruby scripts for learning the gem from a normal Ruby project.
+
+Run them from the gem root:
+
+```bash
+ruby examples/basic_compose.rb
+ruby examples/source_list_dsl.rb
+ruby examples/yaml_plan.rb
+ruby examples/html_input.rb
+ruby examples/standard_composer.rb
+ruby examples/standard_sources_buffer.rb
+ruby examples/advanced_composer.rb
+ruby examples/complex_composer.rb
+```
+
+Each script prints Markdown and writes the same result to `examples/output/*.md`.
+
+The examples use small Markdown and HTML fixtures in `examples/fixtures/`. They are user-facing sample inputs, separate from `test/fixtures/`, which are larger test-only fixtures used by the automated suite.