markdown_composer 0.7.0

data/docs/reference/md_composer_nested.md

@@ -0,0 +1,170 @@
+---
+title: Markdown Composer Nested Syntax
+type: reference
+status: current
+updated: 2026-06-02
+description: Public reference for Markdown Composer nested include syntax, selector-embedded projections, where/take ordering, and structured equivalents.
+---
+
+# Markdown Composer Nested Syntax
+
+### References
+
+| What | Where |
+|------|-------|
+| Select syntax | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Include syntax | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+| Unit tokens | [./md_composer_unit_tokens.md](./md_composer_unit_tokens.md) |
+| Take modifiers | [./md_composer_take.md](./md_composer_take.md) |
+| Where conditions | [./md_composer_where.md](./md_composer_where.md) |
+| Plan normalisation | `gems/markdown_composer/lib/markdown_composer/plan.rb` |
+| Selection resolver | `gems/markdown_composer/lib/markdown_composer/selection_resolver.rb` |
+
+---
+
+## 1. Purpose
+
+Nested syntax lets a Composer expression select parent units, then project child units from inside each match.
+
+Use this doc when you need the shared grammar around `unit[take] where condition { nested include }`. Use the include, take, where, and unit-token references for the full option tables.
+
+## 2. Compact Grammar
+
+The compact selector shape is:
+
+```text
+unit[take] where condition { nested include }
+```
+
+Each part is optional except the unit token.
+
+| Part | Example | Meaning |
+|------|---------|---------|
+| `unit` | `section` | The document unit to match. |
+| `[take]` | `[first:2]` | Narrows ordered matches. |
+| `where condition` | `where title:contains("API")` | Filters matches before take. |
+| `{ nested include }` | `{ heading_title; paragraph[first:1] }` | Projects child units from each match. |
+
+## 3. Where And Take Ordering
+
+Composer applies nested selector filters in this order:
+
+```text
+candidate units -> where -> take -> nested include
+```
+
+Example:
+
+```text
+section[first:2] where title:contains("Release") { heading_title; paragraph[first:1] }
+```
+
+This finds child sections whose title contains `Release`, keeps the first two matching sections, then emits each section title and first paragraph.
+
+## 4. Nested Include Separators
+
+Top-level include strings use commas between include items:
+
+```text
+heading_title, paragraph[first:1]
+```
+
+Nested include braces use semicolons between child include items:
+
+```text
+section[first:2] { heading_title; paragraph[first:1] }
+```
+
+This keeps nested include parsing unambiguous when child expressions contain commas, predicates, brackets, or deeper braces.
+
+## 5. Structured Equivalent
+
+Compact nested include:
+
+```text
+section[first:2] { heading_title; paragraph[first:1] }
+```
+
+Structured equivalent:
+
+```ruby
+{
+  "type" => "section",
+  "take" => { "first" => 2 },
+  "include" => [
+    { "type" => "heading_title" },
+    { "type" => "paragraph", "take" => { "first" => 1 } }
+  ]
+}
+```
+
+Use structured syntax for stored configs, generated plans, and GUI builders.
+
+## 6. Compose Row Pattern
+
+For normal compose rows, keep parent selection in `select` and child projection in `include`:
+
+```ruby
+{
+  "select" => "heading_1_section[first:1]",
+  "include" => "section[first:2] { heading_title; paragraph[first:1] }",
+  "action" => "set"
+}
+```
+
+`select` chooses the parent unit. `include` decides what to emit from inside that parent.
+
+## 7. Recursion
+
+Nested include items can themselves contain nested include blocks:
+
+```text
+section[first:2] { heading_title; section[first:1] { heading_title; paragraph[first:1] } }
+```
+
+Resolution is recursive:
+
+```text
+parent match -> child matches -> child where/take -> child include -> grandchild matches
+```
+
+Keep deeply nested compact syntax for advanced cases only. Prefer structured syntax when a generated plan needs more than one nested level.
+
+## 8. Exclusions
+
+Nested include can combine with exclusions:
+
+```text
+all except section[first:1]
+```
+
+Structured form:
+
+```ruby
+[
+  { "type" => "all" },
+  { "exclude" => { "type" => "section", "take" => { "first" => 1 } } }
+]
+```
+
+Exclusions are evaluated inside the current parent unit, then subtracted from included matches.
+
+## 9. Scope Notes
+
+| Context | Nested support | Notes |
+|---------|----------------|-------|
+| Row `include` | Yes | Primary place for nested projection. |
+| Transform `scope` | Yes | Selector-embedded include can narrow the units transformed. |
+| Target selector | Parsed | Use sparingly; target docs should define action-specific behavior. |
+| Row `select` | Parsed | Prefer the separate row `include` field for normal composition. |
+| `where` conditions | No | `where` supports grouped predicates and field-take, but not nested include projection. |
+
+## 10. GUI Guidance
+
+For UI builders:
+
+- Build parent choice from unit tokens with `support.select`.
+- Build nested include choices from unit tokens with `support.include`.
+- Offer `take` and `where` controls at each nested level.
+- Treat nested include and exclusions as advanced controls.
+- Prefer structured config internally, even when showing compact preview text to authors.

data/docs/reference/md_composer_reference_api.md

@@ -0,0 +1,71 @@
+---
+title: Markdown Composer API Reference
+type: contract
+status: current
+updated: 2026-06-01
+description: Public API reference for Markdown Composer facade methods and result objects.
+---
+
+# Markdown Composer API Reference
+
+### References
+
+| What | Where |
+|------|-------|
+| Plan schema | [./md_composer_reference_plan_schema.md](./md_composer_reference_plan_schema.md) |
+| Diagnostics | [./md_composer_reference_diagnostics.md](./md_composer_reference_diagnostics.md) |
+| Capabilities | [./md_composer_reference_capabilities.md](./md_composer_reference_capabilities.md) |
+
+---
+
+## 1. Main Methods
+
+| Method | Purpose |
+|--------|---------|
+| `MarkdownComposer.compose(sources:, config: nil, plan: nil, options: {})` | Execute a plan and return a `Result`. |
+| `MarkdownComposer.validate(config:, sources: [], options: {})` | Validate a config or plan without composing output. |
+| `MarkdownComposer.normalise(config_or_rows)` | Return canonical plan hash. Alias: `normalize`. |
+| `MarkdownComposer.capabilities(options: {})` | Return JSON-compatible UI/metadata contract. |
+| `MarkdownComposer.plan { ... }` | Build a plan with the Ruby DSL. |
+| `MarkdownComposer.parse_yaml(string)` | Parse YAML into a `Plan`. |
+| `MarkdownComposer.parse_json(string)` | Parse JSON into a `Plan`. |
+| `MarkdownComposer.to_yaml(plan)` | Export a plan to YAML. |
+| `MarkdownComposer.to_json(plan, pretty: true)` | Export a plan to JSON. |
+| `MarkdownComposer.parse_rows(rows)` | Build a plan from row hashes. |
+| `MarkdownComposer.to_rows(plan)` | Export compose rows from a plan. |
+
+## 2. Compose Result
+
+`compose` returns a `MarkdownComposer::Result`.
+
+| Attribute | Meaning |
+|-----------|---------|
+| `success?` | True when there are no errors. |
+| `markdown` | Markdown output. |
+| `html` | HTML output when `output` is `html`; otherwise nil. |
+| `diagnostics` | Non-error diagnostics. |
+| `errors` | Error diagnostics. |
+| `stages` | Optional stage snapshots when enabled. |
+| `to_h` | Serializable result hash. |
+
+## 3. Sources
+
+Sources are hashes or source-like objects with content:
+
+```ruby
+{ "key" => "current", "type" => "current", "markdown" => "# Title\n" }
+```
+
+HTML sources are supported as best-effort/lossy input.
+
+## 4. Validation Result
+
+`validate` returns a hash:
+
+| Key | Meaning |
+|-----|---------|
+| `:valid` | False when any errors are present. |
+| `:plan` | Normalized plan hash. |
+| `:diagnostics` | All diagnostics as JSON-compatible hashes. |
+| `:errors` | Error diagnostics only. |
+

data/docs/reference/md_composer_reference_capabilities.md

@@ -0,0 +1,63 @@
+---
+title: Markdown Composer Capabilities Reference
+type: contract
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer capabilities metadata used by host UIs.
+---
+
+# Markdown Composer Capabilities Reference
+
+### References
+
+| What | Where |
+|------|-------|
+| GUI-oriented source material | [../ai/md_composer_ai_canonical_docs.md](../ai/md_composer_ai_canonical_docs.md) |
+| Registries | [./md_composer_reference_registries.md](./md_composer_reference_registries.md) |
+| Unit tokens | [./md_composer_unit_tokens.md](./md_composer_unit_tokens.md) |
+| Take modifiers | [./md_composer_take.md](./md_composer_take.md) |
+| Where conditions | [./md_composer_where.md](./md_composer_where.md) |
+
+---
+
+## 1. Purpose
+
+`MarkdownComposer.capabilities` returns a JSON-compatible metadata contract for GUI builders and host integrations.
+
+```ruby
+capabilities = MarkdownComposer.capabilities
+```
+
+## 2. Top-Level Keys
+
+```text
+version, headless, fields, formats, sources, actions, targets,
+unit_tokens, take, where, transforms, outputs,
+diagnostic_code_families, policy_options
+```
+
+## 3. Entry Metadata
+
+Registry entries expose labels, tooltips, aliases, meanings, support metadata, `support_status`, and `enabled`.
+
+Use this metadata for UI controls instead of hard-coding token lists.
+
+For the human-facing unit-token table, see [Unit Tokens](./md_composer_unit_tokens.md).
+For the human-facing take table, see [Take Modifiers](./md_composer_take.md).
+For the human-facing field/predicate table, see [Where Conditions](./md_composer_where.md).
+
+## 4. GUI Rules
+
+| Rule | Reason |
+|------|--------|
+| Inspect per-consumer unit token support. | A token can be valid for `include` but not `select`. |
+| Filter transform modes by mode-level `enabled`. | A transform can be visible while a mode is gated. |
+| Treat policy-gated entries separately. | Host policy must opt in. |
+| Do not hide where fields only because `enabled` is false. | Specialized where entries currently expose a misleading enabled flag. |
+
+## 5. Policy Options
+
+| Option | Unlocks |
+|--------|---------|
+| `adapter_policy_tokens` | Token families such as `raw_html`. |
+| `adapter_transforms` | Host-policy transforms such as `adapter` and `sanitise`. |

data/docs/reference/md_composer_reference_diagnostics.md

@@ -0,0 +1,54 @@
+---
+title: Markdown Composer Diagnostics Reference
+type: contract
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer diagnostics and validation errors.
+---
+
+# Markdown Composer Diagnostics Reference
+
+### References
+
+| What | Where |
+|------|-------|
+| API reference | [./md_composer_reference_api.md](./md_composer_reference_api.md) |
+| Plan schema | [./md_composer_reference_plan_schema.md](./md_composer_reference_plan_schema.md) |
+
+---
+
+## 1. Purpose
+
+Diagnostics explain validation and execution problems. Errors block successful composition; warnings report behavior such as empty selections or empty destructive targets.
+
+## 2. Validation Example
+
+```ruby
+validation = MarkdownComposer.validate(config: config, sources: sources)
+validation[:valid]
+validation[:errors]
+validation[:diagnostics]
+```
+
+## 3. Common Codes
+
+| Code | Meaning |
+|------|---------|
+| `source.missing` | A source reference cannot be resolved. |
+| `selection.empty` | A selector matched no content. |
+| `take.invalid` | Take syntax or values are invalid. |
+| `where.invalid` | Where syntax or predicate usage is invalid. |
+| `action.target_required` | Action requires a target. |
+| `target.selector_required` | Action requires selector target, not positional target. |
+| `target.in_place_source_invalid` | `in_place` requires original `source: "buffer"`. |
+| `transform.option_missing` | Required transform option is missing. |
+| `transform.option_unknown` | Transform option is not accepted for that mode. |
+| `yaml.syntax` / `json.syntax` | Import parse error. |
+
+## 4. Debugging Workflow
+
+1. Validate first.
+2. Check diagnostic `path` to find the row and field.
+3. Normalize the plan to inspect canonical tokens.
+4. Run focused compose examples with small input.
+

data/docs/reference/md_composer_reference_plan_schema.md

@@ -0,0 +1,75 @@
+---
+title: Markdown Composer Plan Schema Reference
+type: contract
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer plan shape and row schemas.
+---
+
+# Markdown Composer Plan Schema Reference
+
+### References
+
+| What | Where |
+|------|-------|
+| API reference | [./md_composer_reference_api.md](./md_composer_reference_api.md) |
+| Compose anatomy | [../compose/md_composer_compose_anatomy.md](../compose/md_composer_compose_anatomy.md) |
+| Transform anatomy | [../transform/md_composer_transform_anatomy.md](../transform/md_composer_transform_anatomy.md) |
+
+---
+
+## 1. Top-Level Shape
+
+```ruby
+{
+  "version" => 1,
+  "output" => "markdown",
+  "compose" => [ ... ],
+  "transform" => [ ... ]
+}
+```
+
+| Key | Required | Default |
+|-----|----------|---------|
+| `version` | no | `1` |
+| `output` | no | `markdown` |
+| `compose` | no | empty |
+| `transform` | no | empty |
+
+## 2. Compose Row Shape
+
+```ruby
+{
+  "source" => "current",
+  "select" => "heading_2_section[first:1]",
+  "include" => "all",
+  "action" => "set",
+  "target" => "end",
+  "transforms" => []
+}
+```
+
+`transforms` is used by `modify` and `transform_buffer_target`.
+
+## 3. Transform Row Shape
+
+```ruby
+{
+  "scope" => "output",
+  "transform" => "replace_text",
+  "mode" => "literal",
+  "options" => { "from" => "Draft", "to" => "Final" }
+}
+```
+
+## 4. Import And Export
+
+| Need | API |
+|------|-----|
+| YAML to plan | `MarkdownComposer.parse_yaml(yaml)` |
+| JSON to plan | `MarkdownComposer.parse_json(json)` |
+| Plan to YAML | `MarkdownComposer.to_yaml(plan)` |
+| Plan to JSON | `MarkdownComposer.to_json(plan)` |
+| Rows to plan | `MarkdownComposer.parse_rows(rows)` |
+| Plan to rows | `MarkdownComposer.to_rows(plan)` |
+

data/docs/reference/md_composer_reference_registries.md

@@ -0,0 +1,63 @@
+---
+title: Markdown Composer Registries Reference
+type: contract
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer registry families and metadata.
+---
+
+# Markdown Composer Registries Reference
+
+### References
+
+| What | Where |
+|------|-------|
+| Capabilities | [./md_composer_reference_capabilities.md](./md_composer_reference_capabilities.md) |
+| Unit tokens | [./md_composer_unit_tokens.md](./md_composer_unit_tokens.md) |
+| Take modifiers | [./md_composer_take.md](./md_composer_take.md) |
+| Where conditions | [./md_composer_where.md](./md_composer_where.md) |
+| Compose select | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Transform families | [../transform/md_composer_transform_transforms.md](../transform/md_composer_transform_transforms.md) |
+
+---
+
+## 1. Purpose
+
+Registries define canonical tokens, aliases, labels, tooltips, meanings, support metadata, and capability entries.
+
+Public plans should store canonical tokens after normalization.
+
+## 2. Registry Families
+
+| Family | Used by |
+|--------|---------|
+| Sources | Compose `source` |
+| Actions | Compose `action` |
+| Targets | Compose `target` |
+| Unit tokens | Select, include, target, and transform scope |
+| Take | Bracketed take syntax |
+| Where | Field/predicate/group filtering |
+| Transforms | Transform family and mode metadata |
+
+See [Unit Tokens](./md_composer_unit_tokens.md) for the full public unit-token table with aliases and per-context support.
+See [Take Modifiers](./md_composer_take.md) for bracketed positional narrowing syntax.
+See [Where Conditions](./md_composer_where.md) for the shared field/predicate syntax used by select, include, target, and scope.
+
+## 3. Aliases
+
+Common aliases:
+
+| Alias | Canonical |
+|-------|-----------|
+| `h2_section` | `heading_2_section` |
+| `h2` | `heading_2` |
+| `p` | `paragraph` |
+| `a` | `link` |
+| `img` | `image` |
+| `li` | `list_item` |
+| `whole output` | `output` target position |
+| `in place` | `in_place` target position |
+
+## 4. Structured Data Tokens
+
+`data_block` is a normal selectable structured-data block. `data_path` is include-only. `data_record` and `data_value` are transient derived output node types produced by `data_path(...)`; do not treat them as ordinary post-compose selectors in standalone Markdown output.