@markup-carve/pandoc-carve 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { type CarveAstDocument } from './ast-json.js';
+import { type ConvertOptions, type ConvertResult } from './convert.js';
+import { type ParseOptions } from './parse-options.js';
+import type { PandocDoc } from './pandoc.js';
+export { PANDOC_API_VERSION, type PandocDoc } from './pandoc.js';
+export type { ConvertOptions, ConvertResult } from './convert.js';
+export type { ParseOptions } from './parse-options.js';
+export type { ReverseResult } from './reverse.js';
+export type { CarveAstDocument, CarveAstNode } from './ast-json.js';
+/**
+ * Parse Carve source to the serialized AST of PART 12 - the shape
+ * `resources/ast-schema.json` pins, and the shape every engine's `--to-json`
+ * writes.
+ */
+export declare function carveToCarveAst(source: string, options?: ParseOptions): CarveAstDocument;
+/**
+ * Convert Carve source to a Pandoc document (api-version 1.23.1).
+ *
+ * Returns the document plus a list of degradation warnings for constructs
+ * that have no faithful Pandoc equivalent.
+ */
+export declare function carveToPandoc(source: string, options?: ConvertOptions & ParseOptions): ConvertResult;
+/**
+ * Convert an already-serialized Carve AST - PART 12, from ANY engine, however
+ * it arrived: a `carve --to-json` file, a pipe, an editor's own tree.
+ *
+ * Takes the document as an object or as JSON text. It runs the same conversion
+ * {@link carveToPandoc} does, because the exchange format is what the converter
+ * reads in both cases - no implementation's internals are involved.
+ */
+export declare function carveAstToPandoc(ast: CarveAstDocument | string, options?: ConvertOptions & ParseOptions): ConvertResult;
+/**
+ * Convert Carve source to Pandoc JSON, ready for `pandoc -f json -t <target>`.
+ * Degradation warnings are discarded; use {@link carveToPandoc} to inspect them.
+ */
+export declare function carveToPandocJson(source: string, options?: ConvertOptions & ParseOptions): string;
+/**
+ * The reverse direction: convert a Pandoc document (as emitted by
+ * `pandoc -t json`) to Carve source. Serialization is delegated to
+ * `renderCarve` (the `carve fmt` serializer), so the output carries fmt's
+ * guarantees. Returns the Carve source plus degradation warnings.
+ */
+export declare function pandocToCarve(doc: PandocDoc | string): {
+    carve: string;
+    warnings: string[];
+};
+/**
+ * Convert Pandoc to the canonical Carve exchange AST without forcing it through
+ * Carve 0.1 source. This preserves structural fields, notably Pandoc's optional
+ * short caption, for which the source language intentionally has no spelling.
+ */
+export declare function pandocToCarveAst(doc: PandocDoc | string): {
+    ast: CarveAstDocument;
+    warnings: string[];
+};

package/dist/index.js

@@ -0,0 +1,93 @@
+import * as carve from '@markup-carve/carve';
+import { normalizeCarveAst, parseCarveAst, toCarveAst } from './ast-json.js';
+import { convert } from './convert.js';
+import { parseExtensions } from './parse-options.js';
+import { pandocToCarve as reverse } from './reverse.js';
+export { PANDOC_API_VERSION } from './pandoc.js';
+/**
+ * The engine's own serializer, when the installed engine has one.
+ *
+ * PART 12 section 1: an implementation whose internals differ maps on the way
+ * out. Where the engine does that itself its mapping is authoritative and is
+ * used; the current git pin exports `toAstJson`, while any published release
+ * up to `0.1.3` does not, and there `toCarveAst` applies the section 7
+ * mapping instead. Feature-detected through
+ * a NAMESPACE import on purpose - a named import of an export the installed
+ * version does not have fails at link time, before any check could run.
+ */
+const engineSerializer = carve.toAstJson;
+/**
+ * Parse Carve source to the serialized AST of PART 12 - the shape
+ * `resources/ast-schema.json` pins, and the shape every engine's `--to-json`
+ * writes.
+ */
+export function carveToCarveAst(source, options) {
+    return toCarveAst(carve.parse(source, { extensions: parseExtensions(options) }), engineSerializer);
+}
+/**
+ * Convert Carve source to a Pandoc document (api-version 1.23.1).
+ *
+ * Returns the document plus a list of degradation warnings for constructs
+ * that have no faithful Pandoc equivalent.
+ */
+export function carveToPandoc(source, options) {
+    return convert(carveToCarveAst(source, options), withParser(options));
+}
+/**
+ * The convert options with this module's parser lent to them.
+ *
+ * `convert` reads a serialized AST from any engine and holds no engine of its
+ * own, but metadata block content (`abstract: |`) is Carve SOURCE inside a
+ * YAML string and has to be parsed. This is the only place that owns both, so
+ * it is the place that hands the parser over. An explicit `parseBlocks` wins,
+ * so a caller can supply another engine's.
+ */
+function withParser(options) {
+    return {
+        ...options,
+        parseBlocks: options?.parseBlocks
+            ?? ((source) => carveToCarveAst(source, options).children ?? []),
+    };
+}
+/**
+ * Convert an already-serialized Carve AST - PART 12, from ANY engine, however
+ * it arrived: a `carve --to-json` file, a pipe, an editor's own tree.
+ *
+ * Takes the document as an object or as JSON text. It runs the same conversion
+ * {@link carveToPandoc} does, because the exchange format is what the converter
+ * reads in both cases - no implementation's internals are involved.
+ */
+export function carveAstToPandoc(ast, options) {
+    return convert(normalizeCarveAst(parseCarveAst(ast)), withParser(options));
+}
+/**
+ * Convert Carve source to Pandoc JSON, ready for `pandoc -f json -t <target>`.
+ * Degradation warnings are discarded; use {@link carveToPandoc} to inspect them.
+ */
+export function carveToPandocJson(source, options) {
+    return JSON.stringify(carveToPandoc(source, options).doc);
+}
+/**
+ * The reverse direction: convert a Pandoc document (as emitted by
+ * `pandoc -t json`) to Carve source. Serialization is delegated to
+ * `renderCarve` (the `carve fmt` serializer), so the output carries fmt's
+ * guarantees. Returns the Carve source plus degradation warnings.
+ */
+export function pandocToCarve(doc) {
+    const parsed = typeof doc === 'string' ? JSON.parse(doc) : doc;
+    const { ast, warnings } = reverse(parsed);
+    return {
+        carve: carve.renderCarve(ast),
+        warnings,
+    };
+}
+/**
+ * Convert Pandoc to the canonical Carve exchange AST without forcing it through
+ * Carve 0.1 source. This preserves structural fields, notably Pandoc's optional
+ * short caption, for which the source language intentionally has no spelling.
+ */
+export function pandocToCarveAst(doc) {
+    const parsed = typeof doc === 'string' ? JSON.parse(doc) : doc;
+    const { ast, warnings } = reverse(parsed, 'ast');
+    return { ast: toCarveAst(ast, engineSerializer), warnings };
+}

package/dist/pandoc.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Minimal Pandoc JSON AST types and constructors.
+ *
+ * Shapes follow pandoc-types 1.23 (pandoc 3.x): every node is `{t, c?}`,
+ * verified against `pandoc -t json` output of pandoc 3.5.
+ */
+export declare const PANDOC_API_VERSION: readonly [1, 23, 1];
+export type Attr = [string, string[], [string, string][]];
+export interface PandocNode {
+    t: string;
+    c?: unknown;
+}
+export type Inline = PandocNode;
+export type Block = PandocNode;
+export type MetaValue = PandocNode;
+export interface PandocDoc {
+    'pandoc-api-version': number[];
+    meta: Record<string, MetaValue>;
+    blocks: Block[];
+}
+export declare const emptyAttr: Attr;
+export declare function attr(id?: string, classes?: string[], kvs?: [string, string][]): Attr;
+export declare const Str: (s: string) => Inline;
+export declare const Space: Inline;
+export declare const SoftBreak: Inline;
+export declare const LineBreak: Inline;
+export declare const Emph: (xs: Inline[]) => Inline;
+export declare const Strong: (xs: Inline[]) => Inline;
+export declare const Underline: (xs: Inline[]) => Inline;
+export declare const Strikeout: (xs: Inline[]) => Inline;
+export declare const Superscript: (xs: Inline[]) => Inline;
+export declare const Subscript: (xs: Inline[]) => Inline;
+export declare const SmallCaps: (xs: Inline[]) => Inline;
+export declare const Code: (a: Attr, s: string) => Inline;
+export declare const Link: (a: Attr, xs: Inline[], target: [string, string]) => Inline;
+export declare const Image: (a: Attr, alt: Inline[], target: [string, string]) => Inline;
+export declare const Span: (a: Attr, xs: Inline[]) => Inline;
+export declare const RawInline: (format: string, s: string) => Inline;
+export declare const Note: (blocks: Block[]) => Inline;
+export type QuoteType = 'DoubleQuote' | 'SingleQuote';
+/**
+ * A quotation as pandoc models it: the quote WRAPS its content, and the marks
+ * themselves are not in the tree. That is the shape difference the bridge has
+ * to bridge - Carve's parser resolves each mark to its own
+ * `smart_punctuation` node, so the pair has to be found before it can be a
+ * `Quoted`, and taken apart again on the way back.
+ */
+export declare const Quoted: (kind: QuoteType, xs: Inline[]) => Inline;
+/**
+ * pandoc-types `CitationMode`. There is no locator field anywhere in
+ * `Citation`: citeproc reads the locator out of `citationSuffix`, which is why
+ * pandoc's own markdown reader writes `, p. 33` there.
+ */
+export type CitationMode = 'AuthorInText' | 'SuppressAuthor' | 'NormalCitation';
+export interface Citation {
+    citationId: string;
+    citationPrefix: Inline[];
+    citationSuffix: Inline[];
+    citationMode: {
+        t: CitationMode;
+    };
+    /**
+     * The note number in force where the citation stands - reader bookkeeping,
+     * which every reader regenerates. It is not zero on the way in: pandoc's
+     * markdown reader counts notes closed so far and stamps that plus one, so a
+     * citation in running text before any note carries 1, not 0. Callers pass
+     * the count; see the `noteCount` field of the converter's context.
+     */
+    citationNoteNum: number;
+    citationHash: number;
+}
+export declare function citation(id: string, mode: CitationMode, prefix?: Inline[], suffix?: Inline[], noteNum?: number): Citation;
+export declare const Cite: (citations: Citation[], xs: Inline[]) => Inline;
+export declare const MathInline: (s: string) => Inline;
+export declare const MathDisplay: (s: string) => Inline;
+export declare const Para: (xs: Inline[]) => Block;
+export declare const Plain: (xs: Inline[]) => Block;
+export declare const Header: (level: number, a: Attr, xs: Inline[]) => Block;
+export declare const BlockQuote: (blocks: Block[]) => Block;
+export declare const CodeBlock: (a: Attr, s: string) => Block;
+export declare const RawBlock: (format: string, s: string) => Block;
+export declare const HorizontalRule: Block;
+export declare const Div: (a: Attr, blocks: Block[]) => Block;
+export declare const LineBlock: (lines: Inline[][]) => Block;
+export declare const BulletList: (items: Block[][]) => Block;
+export type ListNumberStyle = 'DefaultStyle' | 'Decimal' | 'LowerAlpha' | 'UpperAlpha' | 'LowerRoman' | 'UpperRoman';
+export type ListNumberDelim = 'DefaultDelim' | 'Period' | 'OneParen' | 'TwoParens';
+export declare const OrderedList: (start: number, style: ListNumberStyle, items: Block[][], delim?: ListNumberDelim) => Block;
+export declare const DefinitionList: (items: [Inline[], Block[][]][]) => Block;
+export declare const Figure: (a: Attr, caption: Inline[] | null, blocks: Block[], shortCaption?: Inline[] | null) => Block;
+export type Alignment = 'AlignLeft' | 'AlignRight' | 'AlignCenter' | 'AlignDefault';
+export interface PCell {
+    attr: Attr;
+    align: Alignment;
+    rowSpan: number;
+    colSpan: number;
+    blocks: Block[];
+}
+export declare const cell: (blocks: Block[], align?: Alignment, a?: Attr) => PCell;
+/**
+ * One pandoc `Row`: an `Attr` and its cells. Pandoc gives a row its own
+ * attribute slot, and Carve's `table_row.attrs` is the same thing, so the row
+ * is a record rather than a bare cell list.
+ */
+export interface PRow {
+    attr?: Attr;
+    cells: PCell[];
+}
+export declare const row: (cells: PCell[], a?: Attr) => PRow;
+/**
+ * One pandoc `TableBody`: `Attr`, `RowHeadColumns`, its own intermediate
+ * header rows, and its body rows.
+ *
+ * A table has a LIST of these. Collapsing them to one loses where a body
+ * begins, which is the only place pandoc records an intermediate header or a
+ * row-head column count.
+ */
+export interface TableBody {
+    attr?: Attr;
+    rowHeadColumns?: number;
+    headRows?: PRow[];
+    bodyRows: PRow[];
+}
+export declare function Table(a: Attr, caption: Inline[] | null, colAligns: Alignment[], headRows: PRow[], bodies: TableBody[], footRows?: PRow[], shortCaption?: Inline[] | null): Block;
+export declare const MetaString: (s: string) => MetaValue;
+export declare const MetaInlines: (xs: Inline[]) => MetaValue;
+export declare const MetaList: (xs: MetaValue[]) => MetaValue;
+export declare const MetaMap: (m: Record<string, MetaValue>) => MetaValue;
+export declare const MetaBool: (b: boolean) => MetaValue;
+/**
+ * Block content in metadata - `abstract`, and any other key a template renders
+ * as more than a phrase. Pandoc's own markdown reader produces this for a YAML
+ * LITERAL BLOCK SCALAR (`abstract: |`) and only for that, whatever the key is
+ * called, which is the rule the bridge follows in both directions.
+ */
+export declare const MetaBlocks: (blocks: Block[]) => MetaValue;

package/dist/pandoc.js

@@ -0,0 +1,117 @@
+/**
+ * Minimal Pandoc JSON AST types and constructors.
+ *
+ * Shapes follow pandoc-types 1.23 (pandoc 3.x): every node is `{t, c?}`,
+ * verified against `pandoc -t json` output of pandoc 3.5.
+ */
+export const PANDOC_API_VERSION = [1, 23, 1];
+export const emptyAttr = ['', [], []];
+export function attr(id, classes, kvs) {
+    return [id ?? '', classes ?? [], kvs ?? []];
+}
+function node(t, c) {
+    return c === undefined ? { t } : { t, c };
+}
+// --- Inline constructors ---
+export const Str = (s) => node('Str', s);
+export const Space = node('Space');
+export const SoftBreak = node('SoftBreak');
+export const LineBreak = node('LineBreak');
+export const Emph = (xs) => node('Emph', xs);
+export const Strong = (xs) => node('Strong', xs);
+export const Underline = (xs) => node('Underline', xs);
+export const Strikeout = (xs) => node('Strikeout', xs);
+export const Superscript = (xs) => node('Superscript', xs);
+export const Subscript = (xs) => node('Subscript', xs);
+export const SmallCaps = (xs) => node('SmallCaps', xs);
+export const Code = (a, s) => node('Code', [a, s]);
+export const Link = (a, xs, target) => node('Link', [a, xs, target]);
+export const Image = (a, alt, target) => node('Image', [a, alt, target]);
+export const Span = (a, xs) => node('Span', [a, xs]);
+export const RawInline = (format, s) => node('RawInline', [format, s]);
+export const Note = (blocks) => node('Note', blocks);
+/**
+ * A quotation as pandoc models it: the quote WRAPS its content, and the marks
+ * themselves are not in the tree. That is the shape difference the bridge has
+ * to bridge - Carve's parser resolves each mark to its own
+ * `smart_punctuation` node, so the pair has to be found before it can be a
+ * `Quoted`, and taken apart again on the way back.
+ */
+export const Quoted = (kind, xs) => node('Quoted', [node(kind), xs]);
+export function citation(id, mode, prefix = [], suffix = [], noteNum = 1) {
+    return {
+        citationId: id,
+        citationPrefix: prefix,
+        citationSuffix: suffix,
+        citationMode: node(mode),
+        citationNoteNum: noteNum,
+        citationHash: 0,
+    };
+}
+export const Cite = (citations, xs) => node('Cite', [citations, xs]);
+export const MathInline = (s) => node('Math', [node('InlineMath'), s]);
+export const MathDisplay = (s) => node('Math', [node('DisplayMath'), s]);
+// --- Block constructors ---
+export const Para = (xs) => node('Para', xs);
+export const Plain = (xs) => node('Plain', xs);
+export const Header = (level, a, xs) => node('Header', [level, a, xs]);
+export const BlockQuote = (blocks) => node('BlockQuote', blocks);
+export const CodeBlock = (a, s) => node('CodeBlock', [a, s]);
+export const RawBlock = (format, s) => node('RawBlock', [format, s]);
+export const HorizontalRule = node('HorizontalRule');
+export const Div = (a, blocks) => node('Div', [a, blocks]);
+export const LineBlock = (lines) => node('LineBlock', lines);
+export const BulletList = (items) => node('BulletList', items);
+export const OrderedList = (start, style, items, delim = 'DefaultDelim') => node('OrderedList', [[start, node(style), node(delim)], items]);
+export const DefinitionList = (items) => node('DefinitionList', items);
+export const Figure = (a, caption, blocks, shortCaption = null) => node('Figure', [a, [shortCaption, caption ? [Plain(caption)] : []], blocks]);
+export const cell = (blocks, align = 'AlignDefault', a = emptyAttr) => ({
+    attr: a,
+    align,
+    rowSpan: 1,
+    colSpan: 1,
+    blocks,
+});
+export const row = (cells, a) => (a ? { attr: a, cells } : { cells });
+function renderCell(c) {
+    return [c.attr, node(c.align), c.rowSpan, c.colSpan, c.blocks];
+}
+function renderRow(r) {
+    return [r.attr ?? emptyAttr, r.cells.map(renderCell)];
+}
+function renderBody(b) {
+    return [
+        b.attr ?? emptyAttr,
+        b.rowHeadColumns ?? 0,
+        (b.headRows ?? []).map(renderRow),
+        b.bodyRows.map(renderRow),
+    ];
+}
+export function Table(a, caption, colAligns, headRows, bodies, footRows = [], shortCaption = null) {
+    // The export side of the same ColWidth policy `reverse.ts`'s `table()`
+    // states: alignment is carried, width is always `ColWidthDefault`. Carve
+    // has no width to carry, and pandoc's writers size a default-width column
+    // themselves, so this is the honest value rather than a placeholder.
+    const colspecs = colAligns.map((al) => [node(al), node('ColWidthDefault')]);
+    return node('Table', [
+        a,
+        [shortCaption, caption ? [Plain(caption)] : []],
+        colspecs,
+        [emptyAttr, headRows.map(renderRow)],
+        bodies.map(renderBody),
+        [emptyAttr, footRows.map(renderRow)],
+    ]);
+}
+// --- Meta constructors ---
+export const MetaString = (s) => node('MetaString', s);
+export const MetaInlines = (xs) => node('MetaInlines', xs);
+export const MetaList = (xs) => node('MetaList', xs);
+export const MetaMap = (m) => node('MetaMap', m);
+export const MetaBool = (b) => node('MetaBool', b);
+/**
+ * Block content in metadata - `abstract`, and any other key a template renders
+ * as more than a phrase. Pandoc's own markdown reader produces this for a YAML
+ * LITERAL BLOCK SCALAR (`abstract: |`) and only for that, whatever the key is
+ * called, which is the rule the bridge follows in both directions.
+ */
+export const MetaBlocks = (blocks) => node('MetaBlocks', blocks);

package/dist/parse-options.d.ts

@@ -0,0 +1,35 @@
+import { type CarveExtension } from '@markup-carve/carve';
+/**
+ * What to enable while READING Carve source.
+ *
+ * Only the source entry points take these: once a document is a serialized
+ * Carve AST, every parse-stage decision has already been made and recorded in
+ * the tree, so `carveAstToPandoc` has nothing to apply them to.
+ *
+ * THE CONTRACT THESE DEFAULTS SERVE: anything `pandocToCarve` can WRITE,
+ * `carveToPandoc` must be able to READ. A construct the bridge chooses on the
+ * way out and cannot recognize on the way back is round-trip loss the bridge
+ * inflicted on itself, and it is invisible - the source looks right, and only
+ * the returned AST is poorer.
+ */
+export interface ParseOptions {
+    /**
+     * Parse `[@key]` as a citation group rather than as an `@mention`.
+     *
+     * ON by default. Citations are a Tier-2 extension, so with them off the
+     * parser reaches the `@` first and `[@doe1990]` becomes
+     * `[`, a `.mention` span, `]` - which is what an imported bibliography
+     * silently turned into, every key of it. The reverse direction writes
+     * `[@key]` for every pandoc `Cite`, so reading it back as a citation is
+     * what closes the loop.
+     */
+    citations?: boolean;
+    /**
+     * Extra Carve extensions to enable while parsing, appended to whatever the
+     * flags above already turned on. For extensions with only render hooks this
+     * is unnecessary - nothing downstream of the parse renders.
+     */
+    extensions?: CarveExtension[];
+}
+/** The extension list a set of {@link ParseOptions} asks for. */
+export declare function parseExtensions(options?: ParseOptions): CarveExtension[];

package/dist/parse-options.js

@@ -0,0 +1,10 @@
+import { citations } from '@markup-carve/carve';
+/** The extension list a set of {@link ParseOptions} asks for. */
+export function parseExtensions(options = {}) {
+    const list = [];
+    if (options.citations !== false)
+        list.push(citations());
+    if (options.extensions?.length)
+        list.push(...options.extensions);
+    return list;
+}

package/dist/reverse.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pandoc JSON AST -> Carve AST.
+ *
+ * The inverse of convert.ts: walks a Pandoc document (api 1.23) and builds
+ * the AST shape `@markup-carve/carve`'s `parse()` produces, so `renderCarve()`
+ * (the `carve fmt` serializer) can turn it into Carve source. Spans that
+ * convert.ts emits as classed degradations (mention, tag, symbol, ext-*, ...)
+ * are recognized and restored to their native Carve nodes, which makes
+ * carve -> pandoc -> carve round-trips clean.
+ */
+import type { PandocDoc } from './pandoc.js';
+interface CNode {
+    type: string;
+    [key: string]: unknown;
+}
+export interface ReverseResult {
+    ast: CNode;
+    warnings: string[];
+}
+export declare function pandocToCarve(doc: PandocDoc, target?: 'source' | 'ast'): ReverseResult;
+export {};