Skip to main content

carve/
lib.rs

1//! Carve — a parser + HTML renderer for the [Carve](https://github.com/markup-carve/carve)
2//! markup language.
3//!
4//! ## Quick start
5//!
6//! ```
7//! let html = carve::to_html("# Hello\n\n/italic/ and *bold*.");
8//! assert!(html.contains("<h1>Hello</h1>"));
9//! assert!(html.contains("<em>italic</em>"));
10//! ```
11//!
12//! Use [`parse`] and [`render_html`] when a caller needs the AST between those
13//! steps. [`from_json`] reads the public AST exchange format, and [`try_to_json`]
14//! reports serialization failures for caller-built trees. HTML and BBCode
15//! importers, and importer functions named `try_*`, return fallible results.
16//!
17//! File inclusion can be run through [`prepare_doc_with_includes`] or as a
18//! separate pass through [`includes::expand_includes`].
19//! The `fs` feature enables the built-in filesystem resolver; disabling default
20//! features leaves resolver choice with the host.
21//!
22//! Implementation status: passes every `.crv` / `.html` pair currently
23//! checked into this crate's `tests/spec` submodule, including tables,
24//! captions / figures, admonitions, abbreviations, mentions, tags,
25//! inline extensions, attributes, and frontmatter.
26
27#![deny(missing_docs)]
28
29mod abbr_budget;
30/// Accessibility lint for Carve source.
31pub mod accessibility;
32pub mod ast;
33pub mod ast_envelope;
34mod ast_fingerprint;
35pub mod ast_json;
36pub mod ast_merge;
37pub mod ast_patch;
38pub mod ast_sidecars;
39pub mod bbcode_migrate;
40mod carrier_markers;
41mod citations;
42pub mod conversion_diagnostics;
43pub mod djot_migrate;
44mod document_ids;
45mod escape;
46mod extension;
47pub mod extensions;
48pub mod html_import;
49mod include_walk;
50/// Opt-in file inclusion with host-supplied resolution and diagnostics.
51pub mod includes;
52/// Incremental parsing snapshots and text-change results.
53pub mod incremental;
54mod index_budget;
55mod inline_carriers;
56pub mod lint;
57mod markdown_assessment;
58#[doc(hidden)]
59pub use markdown_assessment::take_attribute_opener_scan_bytes;
60mod markdown_gfm_autolinks;
61mod markdown_github_alerts;
62pub mod markdown_import;
63mod markdown_strike;
64/// Import and migration results for supported source formats.
65pub mod migration;
66mod parse;
67pub mod profile;
68pub mod profile_filter;
69pub mod prosemirror;
70mod render;
71mod render_ansi;
72mod render_carve;
73mod render_carve_error;
74#[path = "render/render_depth.rs"]
75mod render_depth;
76#[path = "render/render_loss.rs"]
77mod render_loss;
78mod render_markdown;
79mod render_plain;
80#[path = "render/render_text.rs"]
81mod render_text;
82mod roundtrip;
83mod sentinel_run;
84#[path = "source/source_layout.rs"]
85mod source_layout;
86#[path = "source/source_patch.rs"]
87mod source_patch;
88#[path = "source/source_positions.rs"]
89mod source_positions;
90mod stamp;
91/// Chunked HTML output on a fast path that may return `NeedsAst`.
92pub mod stream;
93#[path = "table/table_display_width.rs"]
94mod table_display_width;
95#[path = "table/table_source_metadata.rs"]
96mod table_source_metadata;
97#[path = "table/table_spans.rs"]
98mod table_spans;
99mod table_unicode_18_data;
100#[path = "table/table_width.rs"]
101mod table_width;
102mod translit_map;
103mod wire_fields;
104
105/// Temporary marker for generated line-block columns and terminal rendering.
106/// Authored NUL is normalized before parsing. Published spaces use explicit
107/// `NonBreakingSpace` nodes; verbatim fields contain literal U+00A0.
108pub(crate) const NBSP_PLACEHOLDER: char = '\0';
109/// The Carve specification version this engine implements.
110///
111/// `carve fmt --stamp` writes it into a document and [`needs_review`] compares
112/// an existing stamp against it, so a stale value tells a reader their document
113/// is current when it is not. It is not kept correct by hand: the test
114/// `the_version_a_build_reports_is_the_one_that_shipped` compares it against the
115/// `Version:` field of the vendored grammar on every run.
116///
117/// The version of the crate itself is `CARGO_PKG_VERSION` - derived from the
118/// manifest, never written out a second time here.
119pub const SPEC_VERSION: &str = "0.1";
120
121pub use accessibility::{lint_accessibility, AccessibilityDiagnostic, AccessibilitySeverity};
122pub use ast::*;
123pub use ast_envelope::{
124    from_ast_envelope_json, to_ast_envelope_json, AstEnvelopeError, AstEnvelopeExtension,
125    AstEnvelopeOptions, AstEnvelopeReaderOptions, AST_CONTRACT_VERSION, CORE_AST_VOCABULARY,
126};
127pub use ast_json::{from_json, to_json, try_to_json, AstJsonError, AstJsonErrorKind};
128pub use ast_merge::{
129    merge_ast, merge_ast_with_resolver, MergeConflict, MergeConflictReason, MergeResolution,
130    MergeResult,
131};
132pub use ast_patch::{
133    apply_ast_patch, apply_reversible_ast_patch, ast_patch_from_json, ast_patch_to_json,
134    create_ast_patch, create_reversible_ast_patch, AstPatchError, AstPatchOperation,
135    ReversibleAstPatch,
136};
137pub use ast_sidecars::{
138    authored_provenance, fresh_node_identity, from_annotation_ranges_json, from_node_identity_json,
139    from_provenance_json, parse_with_authored_provenance, to_annotation_ranges_json,
140    to_node_identity_json, to_provenance_json, AnnotationAnchor, AnnotationRange, AnnotationRanges,
141    AstSidecarError, NodeIdentity, NodeIdentityEntry, NodeProvenance, Provenance, ProvenanceOrigin,
142    ProvenanceSource,
143};
144pub use bbcode_migrate::{bbcode_to_carve, BbcodeImportError, BBCODE_MAX_INPUT_LENGTH};
145pub use citations::{
146    parse_locator, CitationMode, Citations, CslDate, CslEntry, CslName, ParsedLocator,
147};
148pub use conversion_diagnostics::{
149    conversion_diagnostics, to_conversion_diagnostics_json, ConversionDiagnostic,
150    ConversionDiagnosticCode, ConversionDiagnostics, ConversionPos,
151    DEFAULT_MAX_CONVERSION_DIAGNOSTICS,
152};
153pub use djot_migrate::djot_to_carve;
154pub use extension::{
155    label_default, AsciiHeadingIds, BeforeRenderContext, BlockMatch, CarveExtension, InlineMatch,
156    MatcherContext, Mode, Options, RenderContext, SmartTypographyMode, SocialLinkKind,
157    SocialLinkResolver, SocialLinkResolverInput, StaticRenderers, LABEL_FOOTNOTE_BACKLINK,
158};
159pub use extensions::{
160    sanitize_svg, Autolink, AutolinkOptions, CodeCallouts, CodeGroup, CodeGroupOptions,
161    ColorSwatch, ContentMode, CrossrefStyle, Details, ExternalLinks, ExternalLinksOptions,
162    FencedRender, FencedRenderOptions, Glossary, HeadingLevelShift, HeadingLevelShiftOptions,
163    HeadingNumbers, HeadingNumbersOptions, HeadingPermalinks, HeadingPermalinksOptions,
164    HeadingReference, HeadingReferenceOptions, ImgFence, Index, ListTable, ListType, MathBlock,
165    MathBlockOptions, Position, QuoteCharacters, SanitizeResult, SanitizeSvgOptions, SmartQuotes,
166    Spoiler, SwatchPosition, SwatchShape, TabNormalize, TableOfContents, TableOfContentsOptions,
167    Tabs, TabsMode, TabsOptions, TocPlacement, UrlGenerator, Wikilinks, WikilinksOptions,
168    SMART_QUOTE_LOCALES,
169};
170pub use html_import::{
171    html_to_ast, html_to_carve, HtmlImportAdapter, HtmlImportDiagnostic, HtmlImportDiagnosticCode,
172    HtmlImportError, HtmlImportMode, HtmlImportOptions, HtmlImportReport, HtmlImportResult,
173    HtmlImportSeverity, ImportConfidence, ImportFidelity, MAX_HTML_IMPORT_DEPTH,
174};
175pub use includes::{
176    expand_includes, expands_for_target, select_include_region, IncludeContext, IncludeDenial,
177    IncludeDependency, IncludeOptions, IncludeRegion, IncludeRegionError, IncludeRegionMode,
178    IncludeResolved, IncludeResolver, IncludeResult, IncludeWarning, DEFAULT_MAX_DEPTH,
179    DEFAULT_MAX_RESOLVER_CALLS, DEFAULT_MAX_WARNINGS,
180};
181#[cfg(feature = "fs")]
182pub use includes::{FileSystemResolver, DEFAULT_MAX_FILE_BYTES};
183pub use incremental::{
184    parse_snapshot, parse_snapshot_with_identity, reparse, IncrementalParse, IncrementalParseError,
185    ParserSnapshot, TextChange,
186};
187pub use lint::{lint_carve, lint_carve_with_options, migrate_case_only_references, LintWarning};
188pub use markdown_import::{
189    markdown_to_ast, markdown_to_carve, migration_raw_heading_ids, try_markdown_to_ast,
190    try_markdown_to_carve,
191};
192pub use migration::{
193    fragment_fixup_diagnostic, migrate_bbcode, migrate_djot, migrate_html, migrate_markdown,
194    try_migrate_markdown, try_migrate_markdown_for_directory,
195    try_migrate_markdown_for_directory_with_destinations, MigrationConfidence, MigrationDiagnostic,
196    MigrationFidelity, MigrationReport, MigrationResult, SourceFormat,
197};
198#[cfg(feature = "experimental-event-parser")]
199pub use parse::parse_experimental_event_blocks;
200#[cfg(feature = "experimental-event-parser-options")]
201pub use parse::parse_experimental_event_blocks_with_options;
202pub use parse::{decision_trace, parse, parse_with_options};
203pub use profile::{DisallowedAction, LinkPolicy, Profile, ProfileViolation, ProfileViolationError};
204pub use profile_filter::{apply_profile, apply_profile_with_typography, ProfileFilterResult};
205pub use prosemirror::{
206    from_prosemirror, from_prosemirror_with_report, to_prosemirror, ProseMirrorDoc,
207    ProseMirrorError, ProseMirrorImport,
208};
209pub use render::{
210    render_html, render_html_owned, render_html_owned_with_options, render_html_with_options,
211    MAX_RENDER_DEPTH,
212};
213pub use render_ansi::{render_ansi, render_ansi_with_options};
214pub use render_carve::{render_carve, render_carve_with_options, CarveWriterOptions};
215pub use render_carve_error::{CarveWriteError, RenderCarveError, SourceUnspellable};
216pub use render_depth::RenderDepthError;
217pub use render_loss::{
218    with_render_loss_report, CheckedRenderOptions, RawNodeType, RenderLoss, RenderLossError,
219    RenderResult, RenderTarget, DEFAULT_MAX_RENDER_LOSSES,
220};
221pub use render_markdown::{render_markdown, render_markdown_with_options, MarkdownRenderError};
222pub use render_plain::{render_plain_text, render_plain_text_with_options};
223pub use source_layout::{parse_with_source_layout, to_source_layout_json};
224pub use source_patch::{
225    apply_source_patch, create_source_patch, source_fingerprint, SourceEdit, SourceEditKind,
226    SourcePatch, SourcePatchError, SourceSuggestion,
227};
228pub use stamp::{needs_review, read_stamp, stamp_carve, Stamp, StampForm};
229pub use stream::{try_render_html_streaming, StreamOutcome};
230
231/// Parse a Carve source string and render it as HTML in one call.
232///
233/// Infallible: the parser caps nesting at its own bound, which sits BELOW the
234/// renderers' ceiling, so the §25 refusal is unreachable from a source string
235/// (see [`RenderDepthError`], which the tree-taking renderers return).
236pub fn to_html(source: &str) -> String {
237    let options = Options::default();
238    if let Some(html) = parse::try_layout_html(source, &options) {
239        return html;
240    }
241    let (doc, crossref_index) = parse::parse_with_render_index(source, &options);
242    render::render_html_owned_with_index(
243        doc,
244        &options,
245        crossref_index,
246        source.contains("[@") || source.contains(":::"),
247        source.contains("[^") || source.contains("^["),
248    )
249    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
250}
251
252/// Parse a Carve source string and render it as Markdown in one call.
253///
254/// Infallible: the parser caps nesting at its own bound, which sits BELOW the
255/// renderers' ceiling, so the §25 refusal is unreachable from a source string
256/// (see [`RenderDepthError`], which the tree-taking renderers return).
257/// Positions are ON for this convenience wrapper: §7 orders collected
258/// definitions by source position, and the footnote map is a BTreeMap, so
259/// without spans the definitions print in LABEL order (carve-rs#686). A caller
260/// that builds its own document and calls the tree-taking renderer keeps
261/// whatever it parsed with; label order is the only order available there.
262pub fn to_markdown(source: &str) -> String {
263    render_markdown(&parse_with_options(
264        source,
265        &Options::default().with_positions(true),
266    ))
267    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
268}
269
270/// Parse a Carve source string and render it as plain text in one call.
271///
272/// Infallible: the parser caps nesting at its own bound, which sits BELOW the
273/// renderers' ceiling, so the §25 refusal is unreachable from a source string
274/// (see [`RenderDepthError`], which the tree-taking renderers return).
275/// Positions are ON for this convenience wrapper: §7 orders collected
276/// definitions by source position, and the footnote map is a BTreeMap, so
277/// without spans the definitions print in LABEL order (carve-rs#686). A caller
278/// that builds its own document and calls the tree-taking renderer keeps
279/// whatever it parsed with; label order is the only order available there.
280pub fn to_plain_text(source: &str) -> String {
281    render_plain_text(&parse_with_options(
282        source,
283        &Options::default().with_positions(true),
284    ))
285    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
286}
287
288/// Parse a Carve source string and render it as ANSI-styled text in one call.
289///
290/// Infallible: the parser caps nesting at its own bound, which sits BELOW the
291/// renderers' ceiling, so the §25 refusal is unreachable from a source string
292/// (see [`RenderDepthError`], which the tree-taking renderers return).
293/// Positions are ON for this convenience wrapper: §7 orders collected
294/// definitions by source position, and the footnote map is a BTreeMap, so
295/// without spans the definitions print in LABEL order (carve-rs#686). A caller
296/// that builds its own document and calls the tree-taking renderer keeps
297/// whatever it parsed with; label order is the only order available there.
298pub fn to_ansi(source: &str) -> String {
299    render_ansi(&parse_with_options(
300        source,
301        &Options::default().with_positions(true),
302    ))
303    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it")
304}
305
306/// Parse a Carve source string and render canonical Carve source in one call.
307///
308/// This formatter is intentionally parse-only: it does not run extension hooks,
309/// heading-id enrichment, or other render-time transforms. It also carries no
310/// [`Options`], so no profile reaches it; callers that need the profile honored
311/// on this target use [`try_to_carve_with_options`].
312/// A DEFAULT `Options` CARRIES NO PROFILE, so the only refusal this can meet is
313/// the writer's own, and this entry point has no way to report one. It leaves
314/// the source as authored rather than aborting or emitting an empty document:
315/// every caller here formats in place (`to_carve_patch` then yields a no-op
316/// patch), so losing the text would be worse than not formatting it. A caller
317/// that needs to SEE the refusal uses [`try_to_carve_with_options`], which both
318/// CLI paths now do (carve-rs#2326).
319pub fn to_carve(source: &str) -> String {
320    try_to_carve_with_options(source, &Options::default()).unwrap_or_else(|_| source.to_string())
321}
322
323/// Prepare canonical formatting as a stale-safe patch without changing source.
324pub fn to_carve_patch(source: &str) -> SourcePatch {
325    let formatted = to_carve(source);
326    let mut patch = create_source_patch(
327        source,
328        &formatted,
329        SourceEditKind::Formatting,
330        "canonical-format",
331    );
332    if !patch.edits.is_empty() && lint::lint_with_recovery(source, &Options::default()).1 {
333        patch.edits.clear();
334        patch.unresolved.push(SourceSuggestion {
335            start: 0,
336            end: patch.source_bytes,
337            replacement: formatted,
338            kind: SourceEditKind::Formatting,
339            code: "invalid-container-metadata".into(),
340            message:
341                "Canonical formatting drops invalid container metadata; review the proposed source."
342                    .into(),
343        });
344    }
345    patch
346}
347
348/// Render HTML and report target-routed raw nodes that were omitted.
349pub fn to_html_with_report(
350    source: &str,
351    checked_options: CheckedRenderOptions,
352) -> Result<RenderResult<String>, RenderLossError> {
353    render_loss::checked(RenderTarget::Html, checked_options, || {
354        render_html_owned(parse_with_options(
355            source,
356            &Options::default().with_positions(true),
357        ))
358        .expect("the parse cap sits below the render ceiling")
359    })
360}
361
362/// Render HTML under `options` and report what the render dropped.
363///
364/// [`to_html_with_report`] renders under the defaults, so it cannot reach a
365/// loss an option produces. Roundtrip export has one: a PART 10 §13a carrier
366/// displaces an authored attribute of its own name, and the drop is REPORTED
367/// rather than silent (ruling markup-carve/carve#2902 question 1).
368///
369/// A row carries a position only where `options` asked for one
370/// ([`Options::with_positions`]); every other field is filled either way.
371pub fn to_html_with_options_and_report(
372    source: &str,
373    options: &Options<'_>,
374    checked_options: CheckedRenderOptions,
375) -> Result<RenderResult<String>, RenderLossError> {
376    render_loss::checked(RenderTarget::Html, checked_options, || {
377        to_html_with_options(source, options)
378    })
379}
380
381/// Render Markdown and report target-routed raw nodes that were omitted.
382pub fn to_markdown_with_report(
383    source: &str,
384    checked_options: CheckedRenderOptions,
385) -> Result<RenderResult<String>, RenderLossError> {
386    render_loss::checked(RenderTarget::Markdown, checked_options, || {
387        let (doc, unattached) = parse::collecting_unattached_block_attrs(|| {
388            parse_with_options(source, &Options::default().with_positions(true))
389        });
390        let rendered = render_markdown(&doc).expect("the parse cap sits below the render ceiling");
391        render_loss::collect_markdown_unattached(unattached);
392        rendered
393    })
394}
395
396/// Render plain text and report every raw node omitted by that target.
397pub fn to_plain_text_with_report(
398    source: &str,
399    checked_options: CheckedRenderOptions,
400) -> Result<RenderResult<String>, RenderLossError> {
401    render_loss::checked(RenderTarget::Plain, checked_options, || {
402        render_plain_text(&parse_with_options(
403            source,
404            &Options::default().with_positions(true),
405        ))
406        .expect("the parse cap sits below the render ceiling")
407    })
408}
409
410/// Render ANSI text and report raw inline nodes. Raw blocks have a visible
411/// `[raw:format]` fallback and therefore are not losses on this target.
412pub fn to_ansi_with_report(
413    source: &str,
414    checked_options: CheckedRenderOptions,
415) -> Result<RenderResult<String>, RenderLossError> {
416    render_loss::checked(RenderTarget::Ansi, checked_options, || {
417        render_ansi(&parse_with_options(
418            source,
419            &Options::default().with_positions(true),
420        ))
421        .expect("the parse cap sits below the render ceiling")
422    })
423}
424
425/// Canonical Carve reports nested list items whose tightness cannot be kept.
426pub fn to_carve_with_report(
427    source: &str,
428    checked_options: CheckedRenderOptions,
429) -> Result<RenderResult<String>, RenderLossError> {
430    render_loss::checked(RenderTarget::Carve, checked_options, || to_carve(source))
431}
432
433/// Parse, apply the feature-restriction profile, and render canonical Carve
434/// source. Enforces the profile's `max_length` on the source bytes before the
435/// parser walks them, exactly as [`try_to_html_with_options`] does, and returns
436/// a [`ProfileViolationError`] when the cap is exceeded or the profile's action
437/// is [`DisallowedAction::Error`] and a disallowed node is found.
438///
439/// The profile is honored here for the same reason it is honored on every other
440/// target: `--carve` parses and re-serializes a whole document, so a host that
441/// normalizes UNTRUSTED markup through it needs the cap that bounds that work,
442/// and it must not get back the raw HTML block a `minimal` profile removes from
443/// every other output. The ingest path already reached that answer -
444/// `prepare_document_for_render` filters before `render_carve` on `--from-json`,
445/// so leaving the parse path unfiltered made one target answer the same flags
446/// two different ways depending on how the document arrived (carve-rs#1191).
447///
448/// Like [`to_carve`] this stays parse-only in every other respect: no extension
449/// hooks, no heading-id enrichment.
450pub fn try_to_carve_with_options(
451    source: &str,
452    options: &Options<'_>,
453) -> Result<String, CarveWriteError> {
454    // BEFORE the parse. `max_length` bounds untrusted input, so it has to be
455    // answered ahead of anything that walks that input - refusing after the
456    // parse means the work the cap exists to prevent has already been done.
457    // Same position, same message shape as `prepare_doc`.
458    if let Some(profile) = &options.profile {
459        let max_length = profile.max_length();
460        if max_length > 0 && source.len() > max_length {
461            return Err(CarveWriteError::Profile(ProfileViolationError {
462                violations: vec![ProfileViolation {
463                    node_type: "document".to_string(),
464                    reason: "max_length_exceeded".to_string(),
465                    reason_description: Some(format!(
466                        "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
467                        source.len()
468                    )),
469                }],
470            }));
471        }
472    }
473    // The SAME text the parser reads. `raw_frontmatter` scans for the block's
474    // closing `---` line on the RAW string while `parse_for_carve` ran on a
475    // normalized copy. On CRLF input the closer scan (`\n---\n`) missed, so `to_carve`
476    // concluded there was no frontmatter while the parser had already found it
477    // - and the document fell through to `render_frontmatter`, which rebuilds
478    // the block from the parsed key/value map. That map has no format token, so
479    // `---toml` came back `---`; and a format the map cannot represent parses
480    // into an EMPTY map, so the whole block was dropped. A lone CR and a leading
481    // BOM reached the same fall-through (carve-rs#732).
482    let normalized = parse::normalize_source(source);
483    let source = normalized.as_ref();
484    let (mut frontmatter, _) = raw_frontmatter(source);
485    let mut doc = parse::parse_for_carve(source);
486    if frontmatter.is_some() {
487        doc.frontmatter.clear();
488        doc.frontmatter_raw = None;
489    }
490    if let Some(profile) = &options.profile {
491        let base_host = options.profile_base_host.as_deref();
492        doc = apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc;
493        // The raw block is held HERE, in a local, not in the tree - the writer
494        // reproduces the bytes the author wrote rather than rebuilding them
495        // from the parsed map. So the filter's own frontmatter strip cannot
496        // reach it, and a denied block would come back out verbatim with every
497        // `title:` / `author:` value the strip exists to remove.
498        if frontmatter.is_some() && !profile.is_type_allowed_on("frontmatter", true) {
499            frontmatter = None;
500        }
501    }
502    // THE WRITER'S REFUSAL IS THE CALLER'S TO HANDLE (carve-rs#2326). This was
503    // an `expect` saying a parsed tree never reaches the render ceiling. The
504    // DEPTH half of that is true; a round-trip refusal is not, and one level
505    // past the parse cap the flattening produces a code node whose value the
506    // writer cannot spell, so a shipped CLI path aborted on valid input.
507    let rendered = render_carve_with_options(
508        &doc,
509        &CarveWriterOptions::default().with_align_tables(options.align_tables),
510    )?;
511    // The writer's own output, unedited. `restore_inline_comments` used to walk
512    // the SOURCE lines here and graft each trailing `%%` back onto the first
513    // formatted line equal to the part before it. It could not repair what it
514    // was written for: `render_carve` emits `InlineNode::Comment` itself, so a
515    // line the writer carried the comment onto already ENDS in the marker and is
516    // therefore not equal to the rendering of the part before it. The graft
517    // landed on some OTHER equal line or matched nothing - inert or harmful,
518    // never corrective - and on `a` over `a %%` inside a line block it wrote the
519    // marker onto both (carve-rs#1076). Only the trailing newline it also
520    // guaranteed is kept.
521    let body = if rendered.ends_with('\n') {
522        rendered
523    } else {
524        format!("{rendered}\n")
525    };
526    Ok(match frontmatter {
527        Some(frontmatter) if body.trim().is_empty() => format!("{frontmatter}\n"),
528        Some(frontmatter) => format!("{frontmatter}\n\n{body}"),
529        None => body,
530    })
531}
532
533fn raw_frontmatter(source: &str) -> (Option<String>, &str) {
534    // The parser's own extent: a `fmt` that disagrees with the parser about
535    // where a frontmatter block ends would rewrite an ordinary line into one
536    // (carve-rs#725, carve-rs#2407). An unclosed block runs to the end of the
537    // document and is written with a closer (carve#5016).
538    let Some((kind, rest_start, content_len, after)) = parse::frontmatter_extent(source) else {
539        return (None, source);
540    };
541    let rest = &source[rest_start..];
542    // The opening delimiter carries the format token for EVERY format, the
543    // default one included: PART 11 section 6b says frontmatter in `yaml` comes
544    // back as `---yaml` and never as a bare `---`. An untyped opener is the case
545    // that clause was written for, not one it forgot - `---` and `---yaml` open
546    // the same block, so nothing in the tree tells them apart, and a writer that
547    // omitted the token would be special-casing a value `frontmatter_format`
548    // distinguishes nowhere except in the parser's leniency rule. A reader's
549    // leniency is not a writer's license.
550    //
551    // The default is the parser's own, from the same constant that fills
552    // `Frontmatter::format` for a bare fence, so the written source and the
553    // published tree cannot disagree about which format the document is in.
554    let open = format!(
555        "---{}",
556        if kind.is_empty() {
557            parse::DEFAULT_FRONTMATTER_FORMAT
558        } else {
559            kind
560        }
561    );
562    let content = &rest[..content_len];
563    // An unclosed block's content ends at the end of the document, line ending
564    // included; a closed one's stops before the closer's line.
565    let content = if content_len == after {
566        content.trim_end_matches('\n')
567    } else {
568        content
569    };
570    let body = &rest[after..];
571    (Some(format!("{open}\n{content}\n---")), body)
572}
573
574/// Parse the source, run `before_render` extension hooks, then apply the
575/// feature-restriction profile (if any) as an AST transform. Enforces the
576/// profile's `max_length` on the source bytes (pre-render) and returns a
577/// [`ProfileViolationError`] when the profile's action is
578/// [`DisallowedAction::Error`] and a disallowed node is found.
579///
580/// This is the shared pipeline position (after parse, before render) used by
581/// every `try_to_*_with_options` entry point, so the profile holds identically
582/// across the HTML, Markdown, plain-text and ANSI renderers.
583fn prepare_doc(
584    source: &str,
585    options: &Options<'_>,
586    effective_mode: Mode,
587    target_is_html: bool,
588) -> Result<ast::Document, ProfileViolationError> {
589    let Some(profile) = &options.profile else {
590        return Ok(parsed_doc_with_hooks(
591            source,
592            options,
593            effective_mode,
594            target_is_html,
595        ));
596    };
597    let max_length = profile.max_length();
598    if max_length > 0 && source.len() > max_length {
599        // Match carve-php / carve-js: an over-length input is a profile
600        // violation surfaced as an error regardless of the configured action.
601        let violation = ProfileViolation {
602            node_type: "document".to_string(),
603            reason: "max_length_exceeded".to_string(),
604            reason_description: Some(format!(
605                "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
606                source.len()
607            )),
608        };
609        return Err(ProfileViolationError {
610            violations: vec![violation],
611        });
612    }
613    let doc = parsed_doc_with_hooks(source, options, effective_mode, target_is_html);
614    let base_host = options.profile_base_host.as_deref();
615    Ok(apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc)
616}
617
618/// Run render-time extension hooks and the configured feature profile on an
619/// already-built document. Used by `--from-json`, where parsing has happened in
620/// another process but render restrictions must still apply.
621pub fn prepare_document_for_render(
622    mut doc: ast::Document,
623    options: &Options<'_>,
624    effective_mode: Mode,
625    target_is_html: bool,
626) -> Result<ast::Document, ProfileViolationError> {
627    // FIRST, ahead of the hooks. A profile's `max_length` bounds UNTRUSTED
628    // INPUT, so it has to be answered before anything walks that input:
629    // `before_render` hooks are where the table of contents and the index
630    // traverse and allocate from the tree, and refusing afterwards means the
631    // work the cap exists to prevent has already been done.
632    //
633    // It also puts the number out of a hook's reach. `before_render` takes the
634    // document by value and hands one back, so a hook could return a document
635    // whose `ingest_payload_len` it had cleared - and a cap read after the
636    // hooks would be a cap whose input the pipeline could rewrite.
637    if let Some(profile) = &options.profile {
638        // Measured, not claimed. On the ingest path the untrusted input is the
639        // payload: it is what got parsed, held and walked. `source_len` cannot
640        // stand in for it there, because that number arrives inside the payload
641        // - a hostile tree claims 0 and renders anything, which is exactly what
642        // `Profile::minimal()` used to accept: an 80 KB payload against a
643        // 10,000 byte cap. `main.rs` already measures the payload for
644        // `--from-json` and says why; this helper is documented as the same
645        // path for a host that has already decoded, so it has to reach the same
646        // answer.
647        let max_length = profile.max_length();
648        let input_len = doc.untrusted_input_len();
649        if max_length > 0 && input_len > max_length {
650            let violation = ProfileViolation {
651                node_type: "document".to_string(),
652                reason: "max_length_exceeded".to_string(),
653                reason_description: Some(format!(
654                    "Input exceeds the profile's maximum length of {max_length} bytes ({input_len} given)."
655                )),
656            };
657            return Err(ProfileViolationError {
658                violations: vec![violation],
659            });
660        }
661    }
662
663    let ctx = extension::BeforeRenderContext::new(options, effective_mode, target_is_html);
664    for ext in &options.extensions {
665        doc = ext.before_render(doc, &ctx);
666    }
667    let Some(profile) = &options.profile else {
668        return Ok(doc);
669    };
670    let base_host = options.profile_base_host.as_deref();
671    Ok(apply_profile_with_typography(doc, profile, base_host, options.smart_typography)?.doc)
672}
673
674/// Parse, run extension hooks, apply the profile, and render to HTML.
675/// Returns an error only when the profile's action is
676/// [`DisallowedAction::Error`] (or `max_length` is exceeded).
677pub fn try_to_html_with_options(
678    source: &str,
679    options: &Options<'_>,
680) -> Result<String, ProfileViolationError> {
681    // HTML honors the configured mode (interactive / static).
682    Ok(
683        render_html_owned_with_options(prepare_doc(source, options, options.mode, true)?, options)
684            .expect(
685                "the parse cap sits below the render ceiling, so a parsed tree never reaches it",
686            ),
687    )
688}
689
690/// Parse, run extension/profile transforms, and serialize the AST as JSON.
691pub fn try_to_json_with_options(
692    source: &str,
693    options: &Options<'_>,
694) -> Result<String, ProfileViolationError> {
695    Ok(to_json(&prepare_doc(
696        source,
697        options,
698        Mode::Interactive,
699        false,
700    )?))
701}
702
703/// Parse and serialize with `options`, returning an empty string on failure.
704///
705/// Use [`try_to_json_with_options`] when the caller needs the error.
706pub fn to_json_with_options(source: &str, options: &Options<'_>) -> String {
707    try_to_json_with_options(source, options).unwrap_or_default()
708}
709
710/// Parse, run extension hooks, apply the profile, and render to Markdown.
711/// Markdown is inherently static, so the render mode is forced to
712/// [`Mode::Interactive`] in the hooks (the HTML-only static path never runs);
713/// the Markdown renderer flattens containers on its own.
714/// Returns a typed writer refusal when a roundtrip carrier cannot be spelled.
715pub fn try_to_markdown_with_options(
716    source: &str,
717    options: &Options<'_>,
718) -> Result<String, CarveWriteError> {
719    let (doc, unattached) = parse::collecting_unattached_block_attrs(|| {
720        prepare_doc(source, options, Mode::Interactive, false)
721    });
722    let rendered = render_markdown_with_options(&doc?, options)?;
723    render_loss::collect_markdown_unattached(unattached);
724    Ok(rendered)
725}
726
727/// Parse, run extension hooks, apply the profile, and render to plain text.
728/// Plain text is inherently static; see [`try_to_markdown_with_options`] for
729/// why the mode is forced to [`Mode::Interactive`] in the hooks.
730pub fn try_to_plain_text_with_options(
731    source: &str,
732    options: &Options<'_>,
733) -> Result<String, ProfileViolationError> {
734    Ok(render_plain_text_with_options(
735        &prepare_doc(source, options, Mode::Interactive, false)?,
736        options,
737    )
738    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it"))
739}
740
741/// Parse, run extension hooks, apply the profile, and render to ANSI text.
742/// ANSI is inherently static; see [`try_to_markdown_with_options`] for why the
743/// mode is forced to [`Mode::Interactive`] in the hooks.
744pub fn try_to_ansi_with_options(
745    source: &str,
746    options: &Options<'_>,
747) -> Result<String, ProfileViolationError> {
748    Ok(render_ansi_with_options(
749        &prepare_doc(source, options, Mode::Interactive, false)?,
750        options,
751    )
752    .expect("the parse cap sits below the render ceiling, so a parsed tree never reaches it"))
753}
754
755/// Parse and run `before_render` extension hooks, WITHOUT applying the profile.
756/// `effective_mode` is the resolved render mode for the target format: the HTML
757/// renderer passes `Options::mode`, the non-HTML renderers force
758/// [`Mode::Interactive`] (static rendering is HTML-only).
759fn parsed_doc_with_hooks(
760    source: &str,
761    options: &Options<'_>,
762    effective_mode: Mode,
763    target_is_html: bool,
764) -> ast::Document {
765    doc_with_hooks(
766        parse_with_options(source, options),
767        options,
768        effective_mode,
769        target_is_html,
770    )
771}
772
773fn doc_with_hooks(
774    mut doc: ast::Document,
775    options: &Options<'_>,
776    effective_mode: Mode,
777    target_is_html: bool,
778) -> ast::Document {
779    let ctx = extension::BeforeRenderContext::new(options, effective_mode, target_is_html);
780    for ext in &options.extensions {
781        doc = ext.before_render(doc, &ctx);
782    }
783    doc
784}
785
786/// Parse, expand `{{ … }}` includes, then run the same extension-hook and
787/// profile pipeline the `to_*` entry points use, returning the prepared
788/// document alongside the include diagnostics.
789///
790/// Expansion sits between PARSE and the hook/profile stages deliberately:
791/// included content is therefore subject to exactly the same extension
792/// transforms and the same profile filtering as content the author typed
793/// directly, so an include can never be a privilege-escalation channel
794/// (spec §19 I7, §25 "File inclusion").
795///
796/// The profile's `max_length` is checked against the INPUT source, before
797/// expansion; amplification through includes is bounded separately by the
798/// include byte budget ([`IncludeOptions::with_max_bytes`]).
799pub fn prepare_doc_with_includes(
800    source: &str,
801    options: &Options<'_>,
802    include_options: &IncludeOptions<'_>,
803    effective_mode: Mode,
804    target_is_html: bool,
805) -> Result<PreparedWithIncludes, ProfileViolationError> {
806    if let Some(profile) = &options.profile {
807        let max_length = profile.max_length();
808        if max_length > 0 && source.len() > max_length {
809            return Err(ProfileViolationError {
810                violations: vec![ProfileViolation {
811                    node_type: "document".to_string(),
812                    reason: "max_length_exceeded".to_string(),
813                    reason_description: Some(format!(
814                        "Input exceeds the profile's maximum length of {max_length} bytes ({} given).",
815                        source.len()
816                    )),
817                }],
818            });
819        }
820    }
821    let expanded = includes::expand_includes_with_extensions(
822        parse_with_options(source, options),
823        source,
824        include_options,
825        &options.extensions,
826    );
827    let doc = doc_with_hooks(expanded.doc, options, effective_mode, target_is_html);
828    let doc = match &options.profile {
829        Some(profile) => apply_profile(doc, profile, options.profile_base_host.as_deref())?.doc,
830        None => doc,
831    };
832    Ok(PreparedWithIncludes {
833        doc,
834        warnings: expanded.warnings,
835        suppressed_warnings: expanded.suppressed_warnings,
836        dependencies: expanded.dependencies,
837    })
838}
839
840/// Output of [`prepare_doc_with_includes`]: the fully prepared document plus
841/// the include diagnostics a host needs for reporting and file watching.
842pub struct PreparedWithIncludes {
843    /// Parsed document after include expansion and render preparation.
844    pub doc: ast::Document,
845    /// Include diagnostics the host can display.
846    pub warnings: Vec<IncludeWarning>,
847    /// Number of include diagnostics hidden by the reporting limit.
848    pub suppressed_warnings: usize,
849    /// Included files the host can watch for changes.
850    pub dependencies: Vec<IncludeDependency>,
851}
852
853/// Infallible HTML entry point. Identical to [`try_to_html_with_options`]
854/// except that profile errors render an empty safe output instead of returning
855/// an error. Callers that need to surface violations should use
856/// [`try_to_html_with_options`].
857pub fn to_html_with_options(source: &str, options: &Options<'_>) -> String {
858    try_to_html_with_options(source, options).unwrap_or_default()
859}
860
861/// Infallible Markdown entry point. See [`to_html_with_options`] for the
862/// error-action fallback behavior.
863pub fn to_markdown_with_options(source: &str, options: &Options<'_>) -> String {
864    try_to_markdown_with_options(source, options).unwrap_or_default()
865}
866
867/// Infallible plain-text entry point. See [`to_html_with_options`].
868pub fn to_plain_text_with_options(source: &str, options: &Options<'_>) -> String {
869    try_to_plain_text_with_options(source, options).unwrap_or_default()
870}
871
872/// Infallible ANSI entry point. See [`to_html_with_options`].
873pub fn to_ansi_with_options(source: &str, options: &Options<'_>) -> String {
874    try_to_ansi_with_options(source, options).unwrap_or_default()
875}
876
877/// Infallible Carve-writer entry point. See [`to_html_with_options`] for the
878/// error-action fallback behavior.
879pub fn to_carve_with_options(source: &str, options: &Options<'_>) -> String {
880    try_to_carve_with_options(source, options).unwrap_or_default()
881}