carve-lang 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d63ffac925c5ff16de3889adf7e5e887cd816a4900cf46304f5da865e00998c2
-  data.tar.gz: cb52a4f8c5c3edca31be9e70c7093ff375aa07ae06d48f240bb15b76d8539691
+  metadata.gz: f75d9a093c48417037884f79d3372f6d8ba90ef5b60781789ec293e68f8a170c
+  data.tar.gz: 39418a3a8ab54c8b9886066a90d5aac6071bea72a6b70467fbf3e955032c6979
 SHA512:
-  metadata.gz: b7c2b1b33a8a979ac4ba2f4b8986e7876188ebe8105c5cb9beb9d55e7f068a04f9bcd785b5837309c5fd408670994c57e3706e39979b36adf1a0c8cbb8226738
-  data.tar.gz: a676302d1f1b343abf78e324bdd48dcedd5146e6637370ef3276f33cab5479c854d149f3b9365865867d1f008b1fe3af086b2201ac1b41e79dbb12c31a3f402c
+  metadata.gz: e9e3c6dddd06a979acc9c6bd100f711b5e32b741f885a82a873547dc72abba3b6b7c64a5861b1bc87cedd62ff85a45ed4a439b2084ab5f4d85deec7678d58112
+  data.tar.gz: e05bd66036ca360b3516161990b02e8e5f38ea140a52dc955fc55b082fc4f7da3d57d7bcdf46711aa4e765aa16682c6371f573ed241eb619434a2fbec0dcfc98

data/CHANGELOG.md

@@ -7,6 +7,156 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-08-18
+
+Everything below is the delta from `v0.1.0`, which is the only version a
+reader can be upgrading from. The engine pin moved seven times inside this
+window and lands on carve-rs `0.1.3` (`a33c42ad`); the intermediate revisions
+are not listed, because no release ever shipped them.
+
+### Security
+
+- **A list-valued URL attribute is probed at every candidate, not at its head**
+  (PART 9 §25, markup-carve/carve#1320). The sanitizer read only the value's
+  leading scheme, which vouches for the whole value only where the whole value
+  is one URL, so `srcset="safe.png 1x, javascript:alert(1) 2x"` passed on its
+  second entry. `srcset`, `imagesrcset`, `ping` and `attributionsrc` are now
+  split into tokens and every candidate is read, and any hit blanks the whole
+  value. The engine embedded in `0.1.0` predates the fix, so the gem published
+  on 2026-07-12 carries the defect.
+
+### Added
+
+- **`Carve.parse` publishes source positions.** Every block node the engine can
+  place carries `pos` with `startLine`, `endLine`, `startColumn`, `endColumn`,
+  `startOffset` and `endOffset`, as PART 12 §4 spells it: lines and columns
+  1-based, offsets 0-based, counted in Unicode codepoints, `endColumn` and
+  `endOffset` exclusive. A node whose span the engine could not determine has
+  no `pos` key at all rather than one holding placeholder numbers - an absent
+  position is a fact a consumer can act on, an invented one is not. Inline
+  nodes do not carry positions yet (markup-carve/carve-rs#333).
+
+- **`Carve.to_html(source, sections: false)` renders headings without the
+  `<section>` wrapper** (#36, PART 9 §13). The id goes back on the `<h*>`
+  alongside its other attributes and the blocks that would have been section
+  children stay siblings. Default `true`, so existing output is unchanged. The
+  wrapper is the one output change that breaks a site whose source migrated
+  cleanly: CSS and JS assuming rendered blocks are direct children of the
+  content container stop matching once a `<section>` sits in between.
+
+- **Every extension the engine registers is reachable from Ruby.**
+  `Carve::EXTENSIONS` lists 31 names instead of 15, adding glossary, index,
+  table-of-contents placement (`::: toc`), heading numbers, heading references,
+  heading level shift, code groups, tabs, the img fence, color swatches, smart
+  quotes, and the remaining fenced-render presets (PlantUML, D2, WaveDrom,
+  Vega-Lite, ABC). The list comes from the engine's registry rather than being
+  typed out in the native binding and again in `lib/carve.rb`. Canonical names
+  are the engine's kebab-case keys; snake_case spellings and the short aliases
+  (`:math`, `:permalinks`, `:mermaid`, `:dot`, `:chart`, `:toc`) still work.
+
+- **Composite figures** (PART 9 §4c). A **bare** `::: figure` fence is no longer
+  a generic container: it is one figure of ordered panels, rendering
+  `<figure class="carve-figure-group">` around a
+  `<div class="carve-figure-panels">` whose members are each a
+  `<figure class="carve-figure-panel">`, and a `^ ` line following the closer
+  becomes the group's `<figcaption>` instead of an ordinary paragraph. A fence
+  carrying a title or a `[label]` keeps the old shape, so a document that named
+  its figure divs renders as before. `Carve.parse` publishes the group as a new
+  `figure_group` node type.
+
+### Changed
+
+- **Breaking (`Carve.parse`): the published tree now matches the reference
+  shape.** A tree from this binding did not interoperate with carve-js or
+  carve-php, so several names and the root's shape moved at once:
+
+  | was | now |
+  |---|---|
+  | `critic_insert` / `critic_delete` / `critic_substitute` | `insert` / `delete` / `substitution` |
+  | `footnote` (both forms) | `footnote_ref` / `inline_footnote` |
+  | `ref_id` | `refId` |
+  | `footnote_defs` | `footnoteDefs` |
+  | `source_len` | `srcByteLength` |
+  | `emoji` | `symbol` (and it carries `attrs`) |
+
+  The root now carries exactly `type`, `children` and `srcByteLength`.
+  Frontmatter and footnote definitions are block nodes in `children` rather
+  than root fields, which PART 12 §7 requires: a root field cannot carry the
+  position §4 requires of every node, and both are source an editor navigates
+  to (carve#411, carve#418). Frontmatter is the first child, carrying `format`
+  and **raw** `content` - not parsed key/values, which could not represent a
+  `---toml` block at all. Anything reading `ast[:frontmatter]` or
+  `ast[:footnoteDefs]` breaks.
+
+- **Breaking (`Carve.parse`): three constructs became their own node types.** A
+  backslash escape is `{"type":"escaped_text","value":"-"}` instead of being
+  folded into surrounding text - the backslash carries intent the character does
+  not, since an author writes `\-\-` precisely so a consumer will not render an
+  en dash (carve#350). A `::: |` fence is `line_block` instead of a `div` with a
+  `.line-block` class, because inside it every newline is a hard break and a
+  class alone could not say which one a node was (carve#359). A block
+  extension's `summary` is a list of inline nodes rather than a plain string,
+  matching the admonition `title` shape. Definition lists publish
+  `definition_term` and `definition_description` nodes
+  (markup-carve/carve-rs#374).
+
+  These are additive for a consumer with a default branch and a compile error
+  for one without.
+
+- **Delimited inline comments carried in from the engine.** `{% … %}` is an
+  inline comment that ends at its closer, alongside the trailing `%%` form that
+  runs to the end of its inline run (PART 9 §21a). Both render nothing; in
+  `Carve.parse` they are the same `comment` node, told apart by a `delimited`
+  field, because the two spell different documents and a writer has to
+  reproduce the one that was written.
+
+- **Language changes carried in from the engine.** Superscript and subscript are
+  braced-only - bare `^x^` and `,x,` are literal text, the markup is `{^x^}` and
+  `{,x,}`. The `:name:` symbol inline was added, with a leading word-boundary
+  guard so `a:b:c`, `10:30:` and `me@example.com` stay literal. Compact semantic
+  spans arrived: `[Tab]{kbd}` renders `<kbd>Tab</kbd>`, with `abbr`, `time` and
+  `kbd` in core and `samp`, `var`, `cite` and `dfn` behind the `semantic-span`
+  extension.
+
+  Every `<th>` carries a `scope` - `col` in the header run, `row` for a
+  `|=` cell in a body row. A cell's attribute block binds after its kind and
+  alignment markers, so a `{...}` following a cell's `=` marker is read as
+  attributes rather than rendered as cell text. A mandatory base class merges
+  into the author's class slot at its authored position rather than leading it,
+  so `:widget[x]{#i .c}` keeps `id` first.
+
+- **Rendering corrections carried in from the engine.** A block-attribute line
+  reaches the nested list it was written for, and a flush-left attribute line is
+  read as attributes rather than as paragraph text. A figure group holds its
+  panels directly. A table's sections and rows keep the attributes they have a
+  slot for. A code block resolves the no-break-space sentinel instead of
+  emitting it. A fence opened inside a
+  container keeps that container open, so a boundary line, a list marker at the
+  content column and a closed fence's residue land where PART 9 §24 puts them
+  rather than folding into the code text. A lazy line folded into a container
+  leaves it open. A caption attaches across at most one blank line, so two blank
+  lines detach it and the image stays an image. A definition body is an
+  indented-block collector, so a line below its column ends it. A heading with
+  no `<section>` wrapper renders the author's attributes first and the generated
+  id last. A frontmatter block whose opener named no format is written back as
+  `---yaml`, and a blank line inside a fenced block under a footnote definition
+  or a definition-list description is written empty rather than indented.
+
+  Reference resolution reaches three places it used to stop short of: a
+  reference inside an inline note, a critic insertion or a critic deletion
+  resolves against the document's definitions; a footnote inside an unresolved
+  reference stays a footnote rather than being swallowed by the failed
+  reference; and a reference tail no longer seals its own link text, so the
+  text a reference link carries survives the frame that resolves it.
+
+  For `Carve.parse` specifically: a nested link and an autolink stay nodes and
+  the renderers unwrap them; a collapsed reference publishes the label it
+  resolves by; a heading's derived display text clones the heading's nodes
+  instead of re-rendering them, so an escaped character in a heading reaches the
+  label; and `attrs.keyValues` is published in the author's source order, the
+  same order the sibling `attrs.order` field states.
+
+
 ## [0.1.0] - 2026-07-12
 
 ### Added
@@ -18,5 +168,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Arrays (every AST node type is covered), enabling custom renderers such as
   [carve-hexapdf](https://github.com/markup-carve/carve-hexapdf).
 
-[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/markup-carve/carve-rb/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/markup-carve/carve-rb/releases/tag/v0.1.0

data/README.md

@@ -54,10 +54,18 @@ Carve.to_html(src, extensions: %w[math-block list-table])
 
 ### Recognized extensions
 
-`autolink`, `details`, `list_table`, `math_block`, `heading_permalinks`,
-`citations`, `code_callouts`, `tab_normalize`, `wikilinks`, `external_links`,
-`fenced_render`, `fenced_render_graphviz`, `fenced_render_chart`, `spoiler`,
-`table_of_contents` (see `Carve::EXTENSIONS`).
+`Carve::EXTENSIONS` is the list, and it comes from the engine rather than from
+a copy kept here that could fall behind it:
+
+```ruby
+Carve::EXTENSIONS
+# => [:autolink, :citations, :"code-callouts", :"code-group", ...]
+```
+
+The canonical names are kebab-case (`:"math-block"`, `:"table-of-contents"`).
+Snake_case spellings (`:math_block`) work as arguments, as do the short aliases
+this binding has always taken: `:math`, `:permalinks`, `:mermaid`, `:dot`,
+`:graphviz`, `:chart`, `:toc`.
 
 An unknown extension name raises `ArgumentError`.
 
@@ -131,6 +139,115 @@ carve-py #1).
 
 An unknown `mode:` value or an unknown `renderers:` key raises `ArgumentError`.
 
+## Symbols
+
+A `:name:` symbol renders its literal `:name:` source unless the name is in the
+**symbols map** passed as `symbols:` (String or Symbol keys, String values):
+
+```ruby
+Carve.to_html("Ship it :rocket: :shrug:", symbols: { "rocket" => "🚀" })
+# => "<p>Ship it 🚀 :shrug:</p>"   (an unmapped name stays literal)
+```
+
+The leading word-boundary guard is unaffected by an active map: `a:b:c`,
+`10:30:` and `me@example.com` never become symbols. A non-String value raises
+`TypeError`.
+
+> **Security: symbol values are TRUSTED RAW output.**
+> A mapped value is inserted into the output **unescaped** - the same trust
+> class as a `renderers:` callable. `{ "b" => "<b>x</b>" }` emits a real `<b>`
+> element, not escaped text. This is deliberate (processor configuration is
+> trusted). **Never build a symbols map out of untrusted / user-supplied
+> input.**
+
+## Section wrappers
+
+A top-level heading is wrapped, along with the content following it up to the
+next same-or-shallower heading, in a `<section>` carrying the heading's id (spec
+PART 9 §13). Only the id moves - `{#install .featured}` gives
+`<section id="install"><h2 class="featured">` - and a heading inside a
+blockquote, div or list item is not wrapped at all.
+
+Pass `sections: false` to render headings flat, with the id back on the `<h*>`:
+
+```ruby
+Carve.to_html("# A\n\np\n")
+# => "<section id=\"A\">\n  <h1>A</h1>\n  <p>p</p>\n</section>"
+
+Carve.to_html("# A\n\np\n", sections: false)
+# => "<h1 id=\"A\">A</h1>\n<p>p</p>"
+```
+
+This is for a host whose CSS or JS assumes rendered blocks are direct children
+of the content container - the `.stack > * + *` spacing idiom, `:first-child`,
+`nth-child()` counting, DOM child walks - all of which stop matching once a
+wrapper sits in between. It is the one output change that breaks a document
+whose *source* migrated cleanly.
+
+Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
+`[Heading][]` references and heading numbering all resolve against the slug
+rather than the element carrying it. The endnotes
+`<section role="doc-endnotes">` is a separate construct and is still emitted.
+
+## Untrusted input
+
+Carve's normative hardening is always on and needs no option: dangerous URL
+schemes are blanked, event-handler attributes like `onclick` are dropped, and the
+bidi override/isolate characters behind Trojan Source are removed from rendered
+text.
+
+Raw passthrough is the deliberate exception. A ` ```=html ` block or a
+`` `…`{=html} `` span renders **verbatim** by design, so it is the one thing
+input you did not author has to switch off:
+
+``` ruby
+Carve.to_html(user_input, safe: true, profile: :comment)
+```
+
+`safe:` escapes those raw blocks and spans instead of emitting them. `profile:`
+restricts which constructs are allowed at all and caps input length -
+`:full`, `:article`, `:comment` or `:minimal`, String or Symbol. An unknown name
+raises `ArgumentError` rather than being ignored.
+
+A profile **rejection** raises too, rather than returning something that looks
+like output:
+
+``` ruby
+Carve.to_html("x" * 20_000, profile: :minimal)
+# ArgumentError: Profile violations: 'document' is not allowed: max_length_exceeded (...)
+```
+
+That matters for untrusted input: the engine's infallible entry point answers a
+rejection with an empty String, which a caller cannot tell from a document that
+legitimately rendered to nothing.
+
+Full recipe, defaults and threat model:
+[Security](https://markup-carve.github.io/carve/security).
+
+## Stored documents and spec versions
+
+`carve fmt --stamp` (in any Carve engine) records the spec version a document was
+last processed under. This gem reads that marker back, so a repository of stored
+`.crv` files can be checked for documents predating a breaking spec change:
+
+``` ruby
+Carve.read_stamp(source)
+# => {version: "0.1", generated_by: "carve-php 0.1.0"}
+
+Carve.needs_review?(source)   # true when the document predates this engine
+```
+
+An **unstamped** document answers `true`: its provenance is unknown, and assuming
+it is current is the unsafe direction. Both marker forms are read, and a marker
+written by any engine reads the same - the format is the contract, not any one
+API - so the answer matches carve-php, carve-js, carve-rs and carve-go on the
+same document.
+
+What a version difference means is the
+[versioning contract](https://markup-carve.github.io/carve/versioning): only
+`[behavior]` changelog entries between the stamped version and yours can require
+a document change.
+
 ## API
 
 | Method | Description |
@@ -139,8 +256,14 @@ An unknown `mode:` value or an unknown `renderers:` key raises `ArgumentError`.
 | `Carve.parse(source)` | Parse Carve source into an AST (tree of Ruby Hashes/Arrays). |
 | `Carve.to_html(source, extensions: [...])` | Render with the named extensions enabled. |
 | `Carve.to_html(source, mode: :static, renderers: {...})` | Render self-contained static HTML with build-time renderers. |
+| `Carve.to_html(source, symbols: {...})` | Render with a `:name:` -> value symbol map (values are raw, see above). |
+| `Carve.to_html(source, safe: true, profile: :comment)` | Render untrusted input: escape `=html` raw blocks/spans, restrict constructs. |
+| `Carve.to_html(source, sections: false)` | Render headings flat, with the id on the `<h*>` instead of a `<section>` wrapper. |
+| `Carve.read_stamp(source)` | Read a document's provenance marker: `{version:, generated_by:}` or `nil`. |
+| `Carve.needs_review?(source)` | Whether a document predates this engine's spec version (unstamped counts as yes). |
 | `Carve.to_html_with_extensions(source, names_array)` | Native primitive (Array of Strings). |
 | `Carve.to_html_full(source, names_array, mode_string, renderers_hash)` | Native static-mode primitive. |
+| `Carve.to_html_full_with_symbols(source, names_array, mode_string, renderers_hash, symbols_hash)` | Native primitive, static mode + symbol map. |
 | `Carve::VERSION` | Gem version. |
 | `Carve::EXTENSIONS` | Array of recognized extension symbols. |
 | `Carve::MODES` | Array of recognized render modes (`:interactive`, `:static`). |
@@ -171,14 +294,32 @@ rake test      # runs the minitest suite
 builds:
 
 ```toml
-carve_rs = { package = "carve", git = "https://github.com/markup-carve/carve-rs", rev = "09c64118223c1574d136c308cfe2a70df8ab5128" }
+carve_rs = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "..." }
 ```
 
-The crate is imported under the alias `carve_rs`. Note: carve-rs has since
-renamed its published crate to `carve-lang` on `main`; this pin predates that
-rename, so `package = "carve"` is correct for this exact `rev`. When bumping to
-a newer carve-rs commit (past the rename), update both the `rev` and
-`package = "carve-lang"`.
+Read the current revision out of `ext/carve/Cargo.toml` rather than from a copy
+here. This section used to quote one, and it drifted three bumps behind the
+manifest before anyone noticed - a duplicated value goes stale the first time
+someone edits the original, and a stale one here is worse than none because it
+reads as authoritative.
+
+The crate is imported under the alias `carve_rs`. It is published as `carve-lang`
+(carve-rs renamed it from `carve`), so a pin at any revision past that rename
+needs `package = "carve-lang"` as above.
+
+When bumping the `rev`, run `rake compile` and commit the resulting
+`ext/carve/Cargo.lock` in the same change. The lock records the resolved
+revision, so leaving it behind means every fresh clone gets a dirty working tree
+on its first build and the gem can resolve to a different engine than the one
+that was tested.
+
+Whether the pin is current is not a judgment call: CI runs the mandatory spec
+corpus through the compiled extension and requires byte-identical HTML, so a pin
+that has fallen behind fails a build. Locally:
+
+```sh
+CARVE_SPEC_CORPUS=/path/to/carve/tests/corpus bundle exec rake test
+```
 
 ## License